Calling APIs

Send the installation token as the Bearer token for partner API endpoints.

Identity

Use the OAuth access token to check who connected and which Better i18n account it belongs to:

curl https://api.better-i18n.com/api/oauth-client/me \
  -H "Authorization: Bearer <access_token>"

Organizations and projects

List organizations the user granted access to:

curl https://api.better-i18n.com/api/oauth-client/organizations \
  -H "Authorization: Bearer bi_oat_d7ab12..." \

List projects in an organization:

curl https://api.better-i18n.com/api/oauth-client/organizations/<org_id>/projects \
  -H "Authorization: Bearer bi_oat_d7ab12..."

Create a CDN-backed project in the granted organization:

curl -X POST https://api.better-i18n.com/api/oauth-client/v1/projects \
  -H "Authorization: Bearer bi_oat_d7ab12..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Marketing site", "slug": "marketing-site", "sourceLanguage": "en" }'

Read project details:

curl https://api.better-i18n.com/api/oauth-client/v1/projects/<project_id> \
  -H "Authorization: Bearer bi_oat_d7ab12..."

Add a target language:

curl -X POST https://api.better-i18n.com/api/oauth-client/v1/projects/<project_id>/languages \
  -H "Authorization: Bearer bi_oat_d7ab12..." \
  -H "Content-Type: application/json" \
  -d '{ "code": "de" }'

Dedicated REST endpoints for keys, translations, publishing, glossary, and Content CMS writes are in active partner rollout. Until they are available in your account, use the Better i18n MCP tools with the same bi_oat_ token for translation key and value operations. See MCP integration.

Scope enforcement

If your token is missing the required scope, you'll get:

{
  "error": "missing_scope",
  "required": "translations:publish"
}

Do not retry this. The user needs to re-authorize with the wider scope. See scopes for the full mapping.

Identity endpoint

/api/oauth-client/me is the only endpoint callable with the access token directly. Organization, project, and resource endpoints require the installation token.

Handling revocation

When a token is revoked, API calls return:

HTTP/1.1 410 Gone
{ "error": "grant_revoked" }

Treat this as a first-class state in your UI — show a "Reconnect" prompt, don't retry.

Next step

See the scope reference for what each scope unlocks.