API key permissions

Learn how admins can restrict an API key’s access to specific endpoints using permissions.

API key permissions let admins limit what a developer API key can do. Instead of one key with full access to every endpoint, you can issue keys that are restricted to specific operations, for example a key that can only translate text or a key that can only read glossaries.

API key permissions are available on request. To enable this feature for your organization, contact your DeepL customer success manager or DeepL support.

How permissions work

Every developer API key is one of two types:

• Unrestricted - the key has no permissions assigned and can call every endpoint. This is the default for any key created before permissions were enabled, and for any key created without selecting custom permissions.
• Scoped - the key has one or more permissions assigned. It can call any endpoint covered by its permissions, plus any endpoint that has no permission requirement. It cannot call endpoints that require a permission the key has not been granted.

Permissions are enforced only on scoped keys. Unrestricted keys retain full access to every endpoint, including endpoints that have permissions defined. Existing keys remain unrestricted by default, but admins can scope them at any time using Edit permissions.

Available permissions

Permissions cover both v2 and v3 endpoints where both versions exist.

Permission	Endpoints it grants access to
Translate text	POST /v2/translate
View glossaries and their entries	GET /v2/glossaries GET /v2/glossaries/{glossary_id} GET /v2/glossaries/{glossary_id}/entries GET /v2/glossary-language-pairs GET /v3/glossaries GET /v3/glossaries/{glossary_id} GET /v3/glossaries/{glossary_id}/entries
Create, modify, and delete glossaries	POST /v2/glossaries DELETE /v2/glossaries/{glossary_id} POST /v3/glossaries PATCH /v3/glossaries/{glossary_id} PUT /v3/glossaries/{glossary_id}/dictionaries DELETE /v3/glossaries/{glossary_id} DELETE /v3/glossaries/{glossary_id}/dictionaries

Endpoints that are not listed above have no permission requirement and remain accessible to every developer API key, scoped or unrestricted. Additional permissions covering more of the API will be added in future updates.

Create a scoped key

Open the DeepL Keys page in your account and select the Translation tab. Click “Create key” and optionally name the key.

Under Permissions, choose one of:

• All access - the key remains unrestricted and can call every endpoint.
• Custom permissions - select one or more permissions from the list. The key can only call endpoints covered by the selected permissions.

Click “Create key” to confirm. The key is created with the chosen permissions and shown once in a popup so you can copy it.

Edit permissions on an existing key

You can change permissions on any existing developer API key, including keys that were originally unrestricted.

In the API keys table, open the key’s menu and select “Edit permissions”. Choose All access to make the key unrestricted, or Custom permissions to select specific permissions. Click “Save” to apply.

Identify scoped and unrestricted keys

The API keys table includes a Permissions column showing each key’s status:

• Keys with permissions assigned display a Scoped badge. Click the badge to view the assigned permissions.
• Keys without permissions display an Unrestricted badge.

Error responses

When a scoped key calls an endpoint it does not have permission to access, the API returns a 403 Forbidden response. To resolve the error, either call an endpoint the key has permission for, or update the key’s permissions to include the required access.

Limitations

• Permissions apply only to developer API keys. Admin API keys cannot be scoped and always have full access to the Admin API.
• Speech-to-Text keys do not currently support permissions.
• Permissions are configured per key. The same user can hold a mix of scoped and unrestricted keys.