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)
`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`	Upload and update media files	`/v1/file/projects/{id}/media/presigned-urls` (POST)
`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`	Upload and update font files	`/v1/file/projects/{id}/fonts/presigned-urls` (POST)
`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/*`
`subscription:read`	View subscription and usage	`/v1/subscription/*` (GET)
`subscription:write`	Manage subscription and add-ons	`/v1/subscription/*` (POST, PATCH)
`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`
`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

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

`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`

Upload and update media files in a project. Currently exercised through presigned-URL endpoints; direct write endpoints are reserved for future use.

Required for: Apps that upload media on the user's behalf

`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`

Upload and update font files in a project. Currently exercised through presigned-URL endpoints; direct write endpoints are reserved for future use.

Required for: Apps that upload fonts on the user's behalf

`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
Manage add-ons
Cancel and reactivate subscriptions

Grants: subscription:read, subscription:write

Required for: Subscription management

`subscription:read`

Read-only subscription access:

View current subscription plan
View usage statistics
View available add-ons

Required for: Displaying subscription info

`subscription:write`

Write access to subscriptions:

Manage add-ons
Cancel and reactivate subscriptions

Required for: Subscription management

`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​

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​