API Scopes

Scopes define which parts of the API your application can access. Request only the scopes your application needs.

Available Scopes

OpenID Connect Scopes

Scope	Description
`openid`	Enable OpenID Connect authentication
`profile`	Access user profile (name, handle)
`email`	Access user email address
`offline_access`	Receive refresh tokens for token renewal

Service Scopes

Scope	Description	Endpoints
`identity`	Full user identity management	`/v1/identity/*`
`identity:read`	Read-only user profile access	`/v1/identity/users/me`, `/oauth/userinfo`
`identity:write`	Update user profile and manage organizations	`/v1/identity/*` (write operations)
`identity:invitations`	Invite people to an organization, send an invitation again and revoke one	`/v1/identity/organizations/{id}/invitations` (POST), `/v1/identity/organizations/{id}/invitations/{invitationId}/resend` (POST), `/v1/identity/organizations/{id}/invitations/{invitationId}` (DELETE)
`identity:delete`	Delete the user's own account, or an organization they own, with a code from their mailbox; not included in `identity`	`/v1/identity/users/me/deletion-code` (POST), `/v1/identity/users/me` (DELETE), `/v1/identity/organizations/{id}/deletion-code` (POST), `/v1/identity/organizations/{id}` (DELETE)
`file`	Full file service access	`/v1/file/*`
`file:read`	Read-only file access	`/v1/file/*` (GET only)
`file:write`	Create and update files	`/v1/file/*` (POST, PATCH, PUT)
`file:delete`	Delete files and resources	`/v1/file/*` (DELETE)
`media`	Full media library access (subset of `file`)	`/v1/file/projects/{id}/media*`
`media:read`	Read-only access to media files	`/v1/file/projects/{id}/media` (GET)
`media:write`	Update and move media files	`/v1/file/projects/{id}/media/{id}` (PATCH), `/v1/file/media/{id}/move` (PATCH)
`media:delete`	Delete media files	`/v1/file/projects/{id}/media/{id}` (DELETE)
`font`	Full font library access (subset of `file`)	`/v1/file/projects/{id}/fonts*`
`font:read`	Read-only access to font files	`/v1/file/projects/{id}/fonts` (GET)
`font:write`	Update and move font files	`/v1/file/projects/{id}/fonts/{id}` (PATCH), `/v1/file/fonts/{id}/move` (PATCH)
`font:delete`	Delete font files	`/v1/file/projects/{id}/fonts/{id}` (DELETE)
`document`	Full document operations	`/v1/document/*`
`document:read`	Read-only document access	`/v1/document/*` (GET, validation)
`document:write`	Create and update documents	`/v1/document/*` (POST, PATCH)
`publisher`	Full publisher access	`/v1/publisher/*`
`publisher:read`	View publication jobs	`/v1/publisher/*` (GET)
`publisher:write`	Create publication jobs	`/v1/publisher/*` (POST)
`converter`	Full converter access	`/v1/converter/*`
`converter:read`	View conversion jobs	`/v1/converter/*` (GET)
`converter:write`	Create conversion jobs	`/v1/converter/*` (POST)
`webhook`	Full webhook management	`/v1/webhook/*`
`webhook:read`	View webhook subscriptions	`/v1/webhook/*` (GET)
`webhook:write`	Create and update webhooks	`/v1/webhook/*` (POST, PATCH)
`webhook:delete`	Delete webhook subscriptions	`/v1/webhook/*` (DELETE)
`subscription`	Full subscription access	`/v1/subscription/*`, `/v1/rate-limits/organizations/{organizationId}/usage`
`subscription:read`	View subscription and usage	`/v1/subscription/*` (GET), `/v1/rate-limits/organizations/{organizationId}/usage`
`subscription:write`	Buy and cancel add-ons, in the portal only	none for apps: those routes answer `403 first_party_only`
`authorization`	OAuth client management	`/v1/identity/oauth/*`

System Scopes

Scope	Description
`authorization`	Manage authentication tokens
`health`	Health check endpoints

Scope Hierarchy

Parent scopes automatically grant all their child scopes. A token with a parent scope can access any endpoint that requires one of its child scopes.

Parent Scope	Grants
`identity`	`identity:read`, `identity:write`, `identity:invitations`
`file`	`file:read`, `file:write`, `file:delete`
`media`	`media:read`, `media:write`, `media:delete`
`font`	`font:read`, `font:write`, `font:delete`
`document`	`document:read`, `document:write`
`publisher`	`publisher:read`, `publisher:write`
`converter`	`converter:read`, `converter:write`
`webhook`	`webhook:read`, `webhook:write`, `webhook:delete`
`subscription`	`subscription:read`, `subscription:write`

Example: A token with file scope can access all file endpoints — GET (read), POST/PATCH (write), and DELETE (delete) operations.

Deprecated Scopes

The following scopes have been renamed and are accepted as aliases during the transition period:

Old Scope	New Scope	Notes
`publisher:publish`	`publisher:write`	Use `publisher:write` in new applications
`converter:convert`	`converter:write`	Use `converter:write` in new applications

The deprecated names will continue to work but may be removed in a future version.

Scope Details

`openid`

Enables OpenID Connect authentication. When included:

The /oauth/userinfo endpoint becomes accessible
ID tokens include the sub (subject) claim

Required for: User identification, SSO integrations

`profile`

Access the user's public profile information:

Display name
Handle (username)

Required for: Personalizing user experience

`email`

Access the user's email address:

Email address
Email verification status

Required for: User communication, account linking

`offline_access`

Receive refresh tokens with access tokens, enabling:

Token renewal without user interaction
Long-running background processes

Required for: Background jobs, persistent sessions

`identity`

Full access to user identity operations:

Read and update user profile
Manage user settings
Access user information
Manage organizations

Grants: identity:read, identity:write, identity:invitations

Required for: User management features

`identity:read`

Read-only access to user profile:

View user information
Cannot modify identity settings

Required for: Profile display, read-only integrations

`identity:write`

Write access to user identity:

Update user profile information
Manage organization settings

Required for: Profile editing, user management

`identity:invitations`

Managing an organization's invitations, and nothing else:

Invite an email address into the organization
Send an invitation again, and revoke one

Narrower than identity:write: it changes no profile, role or setting itself. An invitation as admin does make the person an admin once they accept, as in the portal. Only the organization's owner and admins invite, whatever the token holds. To list the invitations, ask for identity:read as well. See Organization invitations.

Required for: Inviting people from your app, without the rest of identity:write

`identity:delete`

Deleting the signed-in user's own account, or an organization they own:

Mail the user the code that confirms it
Schedule the account for deletion, or delete the organization, with that code

identity does not grant it: ask for it on its own, so the user sees it when they approve your app. Every plan includes it, and it works only with the code the user reads from their own mailbox. See Delete the current user's account and Delete an organization.

Required for: Letting a user delete their account, or an organization they own, from your app

`file`

Full access to the File Service:

Create, read, update, delete teams
Manage projects and templates
Upload and download files
Manage media and fonts
Handle permissions and sharing

Grants: file:read, file:write, file:delete

Required for: Full file management, template editing

`file:read`

Read-only access to the File Service:

View teams, projects, templates
Download files and media
Cannot create or modify resources

Required for: Template rendering, read-only viewers

`file:write`

Write access to the File Service:

Create and update teams, projects, templates
Upload files and media
Cannot delete resources

Required for: Content creation and editing

`file:delete`

Delete access to the File Service:

Delete teams, projects, templates
Remove media and font files

Required for: Full content management

`media`

Full access to the media library only — a narrower alternative to file when an integration should not touch templates, projects, or fonts. Grants media:read, media:write, and media:delete.

Required for: Media-focused integrations (DAM systems, image pipelines)

`media:read`

Read-only access to a project's media library:

List media files in a project
Request presigned URLs to download media

Required for: Read-only media viewers and pickers

`media:write`

Update media files in a project, move them to another project, and restore them from the trash. The presigned-URL endpoint only hands out read links, so it takes media:read; uploading goes through the project's uploads, with file:write.

Required for: Apps that organise a user's media library

`media:delete`

Delete media files from a project.

Required for: Apps that manage a user's media library

`font`

Full access to the font library only — a narrower alternative to file when an integration should not touch templates, projects, or media. Grants font:read, font:write, and font:delete.

Required for: Font management integrations

`font:read`

Read-only access to a project's fonts:

List fonts in a project
Request presigned URLs to download fonts

Required for: Read-only font browsing

`font:write`

Update font files in a project, move them to another project, and restore them from the trash. The presigned-URL endpoint only hands out read links, so it takes font:read; uploading goes through the project's uploads, with file:write.

Required for: Apps that organise a user's font library

`font:delete`

Delete font files from a project.

Required for: Apps that manage a user's font library

`document`

Full access to the Document Service:

Validate Typograph templates
Upgrade templates to newer schema versions
Check template compatibility

Grants: document:read, document:write

Required for: Template validation, schema migration

`document:read`

Read-only document access:

Validate templates
Check compatibility

Required for: Template validation

`document:write`

Write access to documents:

Upgrade template versions

Required for: Schema migration

`publisher`

Full access to the Publisher Service:

Create document generation jobs
Generate PDFs and images from templates
Process CSV data for batch generation
Download generated files

Grants: publisher:read, publisher:write

Required for: Document generation, PDF creation

`publisher:read`

Read-only publisher access:

List and view generation job details
Download generated files

Required for: Monitoring jobs, downloading results

`publisher:write`

Write access to the publisher:

Create document generation jobs

Required for: Triggering document generation

`converter`

Full access to the Converter Service:

Convert InDesign packages to Typograph format
Convert between font formats (TTF, OTF, WOFF, WOFF2)
Convert and resize images

Grants: converter:read, converter:write

Required for: InDesign import, format conversion

`converter:read`

Read-only converter access:

List and view conversion job details
Download converted files

Required for: Monitoring conversion jobs

`converter:write`

Write access to the converter:

Create conversion jobs

Required for: Triggering file conversions

`webhook`

Full access to the Webhook Service:

Create and manage webhook subscriptions
View delivery history
Retry failed deliveries
Delete subscriptions

Grants: webhook:read, webhook:write, webhook:delete

Required for: Event-driven integrations

`webhook:read`

Read-only webhook access:

View webhook subscriptions
View delivery logs

Required for: Monitoring webhooks

`webhook:write`

Write access to webhooks:

Create and update webhook subscriptions
Retry deliveries

Required for: Setting up webhook integrations

`webhook:delete`

Delete access to webhooks:

Delete webhook subscriptions

Required for: Managing webhook lifecycle

`subscription`

Full access to subscription management:

View subscription plan and usage
Buy and cancel add-ons, and cancel and reactivate subscriptions: in the portal only, by the organization's owner. They change the contract and the bill, so an app's token gets 403 first_party_only, and any other member, admins included, gets 403

Grants: subscription:read, subscription:write

Required for: Subscription management

`subscription:read`

Read-only subscription access:

View current subscription plan
View usage statistics, and the rate-limit usage per category (GET /v1/rate-limits/organizations/{organizationId}/usage)
View available add-ons

Required for: Displaying subscription info

`subscription:write`

Write access to subscriptions:

Buy and cancel add-ons: in the portal only, by the organization's owner. An app's token gets 403 first_party_only

Required for: Subscription management in the portal

`authorization`

Manage OAuth applications:

Create and configure OAuth clients
View registered applications
Manage redirect URIs and scopes

Required for: OAuth client management

Requesting Scopes

When obtaining an access token, specify the scopes your application needs:

curl -X POST https://api.typograph.nl/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=file document publisher"

Multiple Scopes

Request multiple scopes by separating them with spaces:

scope=openid profile email file document publisher

Using Parent Scopes

Request a parent scope to get all child permissions:

scope=file publisher converter

This is equivalent to requesting:

scope=file:read file:write file:delete publisher:read publisher:write converter:read converter:write

Requesting only what you need

The media:* and font:* scope families exist so an integration can be granted access to just a user's media or font library, without also exposing templates, projects, or teams. Prefer them over the broader file:* family whenever your application's scope is narrower.

# Example: an app that only manages the user's media library
scope=media:read media:write media:delete openid offline_access

Scope Limitations

You can only request scopes that have been granted to your application
Requesting unauthorized scopes will result in an invalid_scope error
The token will only include scopes that are both requested and authorized

Organization-Based Scope Validation

When a token is issued, the scopes are validated against the organization's subscription:

How it works:

Each OAuth client belongs to an organization
The organization's subscription plan determines which scopes are available
At token creation time, requested scopes are filtered to the organization's allowed scopes
If the organization's subscription changes, the allowed scopes may change accordingly

Example:

Organization subscription:    Professional Plan
Organization allowed scopes:  [file, document, publisher, converter, subscription:read]
Client allowed scopes:        [file, document]
Token requested scopes:       [file, document]
Token granted scopes:         [file, document] ✓

If the organization downgrades to Free plan:

Organization allowed scopes:  [file, document]  (publisher removed)
Client allowed scopes:        [file, document, publisher]
Token requested scopes:       [file, document, publisher]
Token granted scopes:         [file, document] (publisher filtered out)

Key points:

Scopes are controlled at the organization level, not the user level
The organization's subscription determines which scopes are available
Users can freely use OAuth applications without personal scope restrictions
Upgrading your subscription unlocks additional scopes

Common Scope Combinations

Server-to-Server Integration

For backend services that generate documents:

scope=file document publisher converter

User-Facing Application

For applications where users authenticate:

scope=openid profile email file offline_access

Read-Only Access

For viewers and display applications:

scope=file:read identity:read

Document Generation Only

For services that only generate documents:

scope=publisher:write file:read

Webhook Consumer

For event-driven applications:

scope=webhook file:read

Full Management

For applications that need complete access:

scope=openid profile email identity file document publisher converter webhook subscription offline_access

Checking Granted Scopes

Token Response

The token response includes the granted scopes:

{
  "access_token": "typ_abc123...",
  "token_type": "Bearer",
  "expires_in": 172800,
  "scope": "file document publisher"
}

Token Introspection

Verify scopes for an existing token:

curl -X POST https://api.typograph.nl/oauth/introspect \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=YOUR_ACCESS_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

UserInfo Endpoint

For tokens with openid scope:

curl https://api.typograph.nl/oauth/userinfo \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

403 Forbidden

Returned when your token lacks the required scope:

{
  "error": "insufficient_scope",
  "error_description": "Token does not have the required scope: publisher:write"
}

invalid_scope

Returned during token request when requesting unavailable scopes:

{
  "error": "invalid_scope",
  "error_description": "The requested scope 'subscription:write' is not available for this client"
}

Available Scopes​

OpenID Connect Scopes​

Service Scopes​

System Scopes​

Scope Hierarchy​

Deprecated Scopes​

Scope Details​

openid​

profile​

email​

offline_access​

identity​

identity:read​

identity:write​

identity:invitations​

identity:delete​

file​

file:read​

file:write​

file:delete​

media​

media:read​

media:write​

media:delete​

font​

font:read​

font:write​

font:delete​

document​

document:read​

document:write​

publisher​

publisher:read​

publisher:write​

converter​

converter:read​

converter:write​

webhook​

webhook:read​

webhook:write​

webhook:delete​

subscription​

subscription:read​

subscription:write​

authorization​

Requesting Scopes​

Multiple Scopes​

Using Parent Scopes​

Requesting only what you need​

Scope Limitations​

Organization-Based Scope Validation​

Common Scope Combinations​

Server-to-Server Integration​

User-Facing Application​

Read-Only Access​

Document Generation Only​

Webhook Consumer​

Full Management​

Checking Granted Scopes​

Token Response​

Token Introspection​

UserInfo Endpoint​

Scope-Related Errors​

403 Forbidden​

invalid_scope​