Integration Scopes

Sometimes a downstream integration needs to know that a request belongs to an authenticated user of your tenant — and nothing more than that. Handing it a session Access Token gives it far more: the user's licenses, permissions and linked authentications, in a credential that every ordinary azuma doa endpoint accepts for the whole of the tenant's configured access-token lifespan.

Integration Scopes solve this. A tenant defines a named scope, and azuma doa mints a deliberately minimal token for it.

What an integration token contains

Property	Value
sub	the user's account ID — an integration token still says which user it is about
ext claims	tenant_id — and nothing else
aud	exactly one audience, {applicationId}-azmscope-{scope}
Lifetime	the lifespan configured for that scope
Refreshable	never — mint a new one instead
Accepted by	the introspection endpoint only; every ordinary azuma doa endpoint rejects it

See Tokens for the full claim table and a sample.

Because the audience is derived from the scope, a token minted for one integration cannot be replayed against another — even within the same application.

Configuring a scope

In the developer portal, open tenant → Settings → Security → Token Data Settings. Each entry in the Scopes list has three parts:

Field	Description
Scope	The name a client requests, e.g. partner-acme.
Modes	Which doors may mint it — Login (ID login only for now) and/or Token exchange. At least one is required; to disable a scope, remove it from the list.
Lifetime	The access token's lifetime in minutes, between 1 and 1440. A new entry starts at 5.

A tenant may configure up to 32 scopes.

note

Do not confuse the per-scope Lifetime with Access Token: Lifespan in Minutes at the top of the same card — that one governs ordinary session tokens and has no effect on integration tokens.

Two switches on the same card control the doors for the whole tenant:

• Integration Scopes: Login — allow a configured scope to be requested at login.
• Integration Scopes: Token Exchange — allow a session token to be exchanged for a restricted one.

Both halves of the gate must be open

A scope is only mintable when the mode is listed on the scope and the corresponding tenant switch is on. Neither substitutes for the other, and turning a switch off disables that door for every scope at once.

Naming rules

A scope name may be up to 64 characters of lowercase a–z, digits 0–9, and the separators -, ., : and _. A separator may only ever sit between other characters, never at the start or the end.

These names are rejected, because azuma doa already uses them:

• The reserved names, in full: openid, offline_access, offline, profile, email, licenses, permissions_app, permissions_core, tenants, tenant_ids and health-id-epa-integration. Most, but not all, of these also appear under Predefined Scopes.
• Anything beginning with azm, or ending with _admin.
• Anything containing azmscope, which marks a restricted audience.
• Anything containing health-id-epa-integration — see Health-ID ePA Integration. The match is deliberately "contains" rather than "equals": the audience ends with the scope name, so a scope such as acme-health-id-epa-integration would produce an audience that tail-matches the ePA one.

Minting a token

Mode	How
Login (ID login)	Request the scope during an ID login. Requires Integration Scopes: Login.
Token exchange	Trade a session token you already hold — from your app, or from your backend. Requires Integration Scopes: Token Exchange. See Integration Token Exchange.

A configured scope must always be requested on its own. Bundling it with offline_access, licenses or a second configured scope is rejected — otherwise the extra scope would ride along in scp and a partner reading scp rather than aud could mistake it for authorization nobody granted.

The lifespan is a ceiling, not a guarantee

A token minted at login gets the configured lifespan exactly. A token minted by exchange gets whichever is shorter: the configured lifespan, or the remaining life of the token it was derived from. Always read expiresIn on the response rather than assuming the configured value.

Changing the configuration

Removing a scope stops new tokens being minted for it. Tokens already issued stay valid until they expire — revoke the session if you need them gone sooner. See Integration Token Exchange.

Not the Google/Apple token exchange

azuma doa also supports trading a Google or Apple ID token for a session token. That is a different feature — see Social Token Exchange.