From def8128e4d07b66f1387b48ff882a128fb7d94a8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0ejla=20=C4=8Cebiri=C4=87?= Date: Wed, 27 May 2026 15:36:45 +0100 Subject: [PATCH 1/2] docs: Add API key permissions page Explains how admins can scope developer API keys to specific endpoints, lists the available permissions and the endpoints they cover, and walks through the create / edit flows in the account UI. Co-Authored-By: Claude Code --- .../admin-api/api-key-permissions.mdx | 78 +++++++++++++++++++ docs.json | 1 + 2 files changed, 79 insertions(+) create mode 100644 api-reference/admin-api/api-key-permissions.mdx diff --git a/api-reference/admin-api/api-key-permissions.mdx b/api-reference/admin-api/api-key-permissions.mdx new file mode 100644 index 00000000..002a89bb --- /dev/null +++ b/api-reference/admin-api/api-key-permissions.mdx @@ -0,0 +1,78 @@ +--- +title: "API key permissions" +description: "Learn how admins can restrict an API key's access to specific endpoints using permissions." +public: true +--- + +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 and can only call the endpoints those permissions cover. Calls to other endpoints are rejected. + + + 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 + +| **Permission** | **Endpoints it grants access to** | +|:---|:---| +| Translate text | Text translation endpoints (`/v2/translate`) | +| View glossaries and their entries | Glossary read endpoints (`GET /v3/glossaries`, `GET /v3/glossaries/{glossary_id}`, `GET /v3/glossaries/{glossary_id}/entries`) | +| Create, modify, and delete glossaries | Glossary write endpoints (`POST`, `PATCH`, `PUT`, and `DELETE` on `/v3/glossaries`) | + +Additional permissions covering more of the API will be added in future updates. + +### Create a scoped key + +Open the [DeepL Keys](https://www.deepl.com/your-account/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. + + + ![](/_assets/images/api-key-permissions-create.png) + + +### 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. + + + ![](/_assets/images/api-key-permissions-edit.png) + + +### 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. + + + ![](/_assets/images/api-key-permissions-badges.png) + + +### 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. diff --git a/docs.json b/docs.json index b3467ad7..bcf569c0 100644 --- a/docs.json +++ b/docs.json @@ -296,6 +296,7 @@ ], "drilldown": false }, + "api-reference/admin-api/api-key-permissions", { "group": "Usage & Quota", "pages": [ From c5cf70990aca35756050dbbb74d342d0c4bf6806 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0ejla=20=C4=8Cebiri=C4=87?= Date: Thu, 28 May 2026 10:02:37 +0100 Subject: [PATCH 2/2] docs: Enumerate all endpoints in API key permissions table List every publicly documented v2 and v3 endpoint each scope grants, with links to the matching API reference pages, and clarify that endpoints without a permission requirement remain accessible to scoped keys. Co-Authored-By: Claude Code --- api-reference/admin-api/api-key-permissions.mdx | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/api-reference/admin-api/api-key-permissions.mdx b/api-reference/admin-api/api-key-permissions.mdx index 002a89bb..b4fd17b1 100644 --- a/api-reference/admin-api/api-key-permissions.mdx +++ b/api-reference/admin-api/api-key-permissions.mdx @@ -15,7 +15,7 @@ API key permissions let admins limit what a developer API key can do. Instead of 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 and can only call the endpoints those permissions cover. Calls to other endpoints are rejected. +- **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**. @@ -23,13 +23,15 @@ Every developer API key is one of two types: ### Available permissions +Permissions cover both v2 and v3 endpoints where both versions exist. + | **Permission** | **Endpoints it grants access to** | |:---|:---| -| Translate text | Text translation endpoints (`/v2/translate`) | -| View glossaries and their entries | Glossary read endpoints (`GET /v3/glossaries`, `GET /v3/glossaries/{glossary_id}`, `GET /v3/glossaries/{glossary_id}/entries`) | -| Create, modify, and delete glossaries | Glossary write endpoints (`POST`, `PATCH`, `PUT`, and `DELETE` on `/v3/glossaries`) | +| **Translate text** | [`POST /v2/translate`](/api-reference/translate/request-translation) | +| **View glossaries and their entries** | [`GET /v2/glossaries`](/api-reference/glossaries/list-all-glossaries)
[`GET /v2/glossaries/{glossary_id}`](/api-reference/glossaries/retrieve-glossary-details)
[`GET /v2/glossaries/{glossary_id}/entries`](/api-reference/glossaries/retrieve-glossary-entries)
[`GET /v2/glossary-language-pairs`](/api-reference/multilingual-glossaries/list-language-pairs-supported-by-glossaries)
[`GET /v3/glossaries`](/api-reference/multilingual-glossaries/list-all-glossaries)
[`GET /v3/glossaries/{glossary_id}`](/api-reference/multilingual-glossaries/retrieve-glossary-details)
[`GET /v3/glossaries/{glossary_id}/entries`](/api-reference/multilingual-glossaries/retrieve-glossary-entries) | +| **Create, modify, and delete glossaries** | [`POST /v2/glossaries`](/api-reference/glossaries/create-a-glossary)
[`DELETE /v2/glossaries/{glossary_id}`](/api-reference/glossaries/delete-a-glossary)
[`POST /v3/glossaries`](/api-reference/multilingual-glossaries/create-a-glossary)
[`PATCH /v3/glossaries/{glossary_id}`](/api-reference/multilingual-glossaries/edit-glossary-details)
[`PUT /v3/glossaries/{glossary_id}/dictionaries`](/api-reference/multilingual-glossaries/replaces-or-creates-a-dictionary-in-the-glossary-with-the-specified-entries)
[`DELETE /v3/glossaries/{glossary_id}`](/api-reference/multilingual-glossaries/delete-a-glossary)
[`DELETE /v3/glossaries/{glossary_id}/dictionaries`](/api-reference/multilingual-glossaries/deletes-the-dictionary-associated-with-the-given-language-pair-with-the-given-glossary-id) | -Additional permissions covering more of the API will be added in future updates. +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