diff --git a/documentation/docs/localizer/users.md b/documentation/docs/localizer/users.md index ec41af036b..e0149c8b57 100644 --- a/documentation/docs/localizer/users.md +++ b/documentation/docs/localizer/users.md @@ -111,6 +111,20 @@ It’s possible to set the default homepage displayed when visiting Pontoon as a ![LOCALES tab in translation tools](../assets/localizer/users/translation_locales.png "LOCALES tab in translation tools") +### Personal Access Tokens + +Users can create Personal Access Tokens (PAT) which are required for accessing some endpoints of the Pontoon [REST API](https://github.com/mozilla/pontoon/blob/main/pontoon/api/README.md). + +To create a PAT, the user must enter a suitable token name no longer than 32 characters. The generated token can be used with the REST API as follows: + +```bash +curl \ + -H "Authorization: Bearer " \ + https://example.com/api/v2/resource/ +``` + +PATs can be manually deleted at any time and automatically expire after one year. + ### Account removal Users can delete their account by scrolling to the `Account Management` section, where a button reading `Delete Account` is located. Once clicked, the user will need to diff --git a/pontoon/api/README.md b/pontoon/api/README.md index c255f98197..80de230cfb 100644 --- a/pontoon/api/README.md +++ b/pontoon/api/README.md @@ -2,7 +2,21 @@ Pontoon provides a set of [RESTful](https://developer.mozilla.org/en-US/docs/Glossary/REST) endpoints via the [Django REST Framework](https://www.django-rest-framework.org/), accessible under `/api/v2/`. -> 🔐 Added on September 2, 2025 at 12:37 UTC: The REST API is in beta. While stable for general use, its structure may change as we continue development. +## Authentication + +Most endpoints are publicly accessible and require no authentication. A few endpoints require an authenticated user. + +Requests can be authenticated either with a session cookie or with a Personal Access Token (PAT). You can create a PAT from your [user settings](https://pontoon.mozilla.org/settings/) page (see the [User Accounts & Settings](https://github.com/mozilla/pontoon/blob/main/documentation/docs/localizer/users.md#personal-access-tokens) documentation for details). + +Send the token in the `Authorization` header using the `Bearer` scheme: + +```bash +$ curl \ + -H "Authorization: Bearer " \ + "https://example.com/api/v2/pretranslate/" +``` + +A PAT automatically expires one year after it is created, and can be deleted manually at any time. Requests made with an invalid or expired token are rejected. ## JSON Mode