Licensed to be used in conjunction with basebox, only.
// admin
API permissions
Overview
What an API key can do: it accesses the OpenAI-compatible and the REST API on behalf of your organisation and uses the models enabled for your organisation. This page explains the scope of a key, what you can control with it and how to limit access.
What it is for
API keys are the entry point for software: scripts, custom applications, editor integrations, coding agents. As an administrator you decide whether such access exists, how many keys there are and for whom. Creating and deleting: API keys.
Where to find the setting
Administration → API keys. The section appears only if your licence covers API use – and on basebox Server only if the Platform Operator has set AISRV_ENABLE_REST_API=true.
What a key can do
| Access | Scope |
|---|---|
| Chat completions | POST /v1/chat/completions (OpenAI-compatible) and POST /rest/v1/chat/completions (REST) |
| Models | GET /v1/models lists the models enabled for your organisation; exactly these can be used by the key |
| Reasoning | Thinking modes can be controlled via the API if the model supports them |
| Tool calling | Function calls defined by the connecting application itself |
| Swagger UI | /v1/api/docs for testing |
A key is always bound to one organisation – the one it was created in. Every request carries the key as bearer token and the X-Realm header with the organisation's realm (Cloud: your subdomain; Server: usually primary).
What a key cannot do
- No administration. Users, groups, apps or settings cannot be managed via the API.
- No foreign organisations. A key acts only within its organisation's realm.
- No user identity. Requests run on behalf of the organisation, not a person. Connectors with personal credentials are therefore not available to the API.
- No graded permissions per key. All keys of an organisation have the same scope; there are no scopes for individual models or apps.
Step by step: limiting access
Because keys cannot be restricted individually, you control via number, assignment and lifetime:
- One key per integration. Use descriptive names ("crm-export", "vscode-team-a"). That way you can see in the table what belongs to what and revoke selectively.
- Issue only to responsible people. The key is shown only once; whoever receives it is responsible for storing it securely (password manager, environment variable – never in Git).
- Review regularly. Check the Created column and delete keys whose integration no longer runs. Deletion takes effect immediately.
- Watch consumption. The Dashboard reports usage of the OpenAI-compatible API separately from the web interface. Unusual spikes are a reason to rotate a key.
- Limits per organisation cap total consumption – including via the API. See Settings.
- Rotation. Create a new key, enter it in the integration, delete the old one.
Notes
A key is a password for your organisation
Whoever holds the key can make requests and consume tokens on behalf of your organisation. Treat it accordingly and revoke it immediately on any suspicion.
Note
- Your organisation's system prompt also applies to requests via the API.
- An invalid key returns a precise authentication error (401); a missing licence or permission a 403. Error codes in detail: Error handling.
- For Anthropic models, basebox adds no artificial instructions via the API.
Frequently asked questions
Can I allow a key only one specific model? No. A key can use all models enabled for the organisation. Limit the model list at organisation level – see Enabling models.
Can a user without the admin role create a key? No. Administrators only.
Can I see which requests were made with which key? The dashboard shows the organisation's total API consumption. A breakdown per key is currently not available in the interface.
Does a key expire? No, keys are valid until deleted. Plan rotation yourself.
Need help? Contact support