Tokens

azuma doa issues three types of tokens depending on the authentication flow:

• Access Token: Used to authenticate API requests.
• Identity Token: Contains user identity information (specific to OpenID Connect flows).
• Refresh Token: Used to obtain new access tokens without re-authenticating the user.

Two restricted variants of the Access Token also exist, for handing to a downstream integration — see Integration Scopes.

For more details, refer to the OAuth 2.0 Specification.

Device Binding

In the Device Binding flow azuma doa issues only Access Token and Refresh Token.

Access Token format

{
  "aud": [
    "803ad030-10a2-417a-bd19-7ad7ccc2dc9d"
  ],
  "client_id": "803ad030-10a2-417a-bd19-7ad7ccc2dc9d",
  "exp": 1751195134,
  "ext": {
    "authorized_scopes": [],
    "kind": "initial",
    "licenses": [],
    "linked_authentications": [],
    "permissions_app": [],
    "security_mode": "device-binding",
    "tenant_id": "d23e6db7-683b-4411-9ede-8ec040816de7"
  },
  "iat": 1751191533,
  "iss": "https://oidc.pie.azuma-health.tech",
  "jti": "d220c0e7-9b85-456f-b503-1d04505a6f6f",
  "nbf": 1751191533,
  "scp": [
    "offline_access",
    "permissions_app",
    "licenses"
  ],
  "sub": "f09af826-8b73-46d6-80c5-57646e4d1384"
} 

Claim	Description
aud	Contains your application-ID
client_id	Your application-ID, that the device binding tokens were requested for.
ext: authorized_scopes	The scopes the client was authorized for. This is always empty in the device binding flow.
ext: kind	initial for the initially returned token after user authentication. refresh for a token that was retrieved via Refresh Token.
ext: licenses	Contains user licenses if defined and assigned.
ext: linked_authentications	Contains the linked authentications (see below for format).
ext: permissions_app	Contains user permissions if defined and assigned.
ext: security_mode	Always set to device-binding for the device binding flow.
ext: tenant_id	The tenant ID.
scp	Scopes.
exp, iat, iss, jti, nbf	Default claims

Linked Authentications

{
  "provider": "mimoto",
  "sub": "https://gsi.dev.gematik.solutions-*id*-https://mimoto-test.pie.azuma-health.tech/oidcf/azuma-demo-tu"
}

Currently, only mimoto is supported.

Authorization Code

Access Token Format

The format for access tokens in the Authorization Code flow will be documented in a future update. Stay tuned for more details.

Client Credentials

Access Token format

{
  "client_id": "159c733f-f1e9-4e9c-96c7-248486408b40",
  "exp": 1754066469,
  "ext": {
    "authorized_scopes": [
      "tenant_admin"
    ],
    "tenant_id": "71c470c6-f6a1-4e59-b105-d8587c364f47"
  },
  "iat": 1754062869,
  "iss": "https://oidc.pie.azuma-health.tech",
  "jti": "388fbeaf-5691-44d1-b2b7-00e7cf3a3cad",
  "nbf": 1754062869,
  "scp": [
    "71c470c6-f6a1-4e59-b105-d8587c364f47_admin"
  ],
  "sub": "159c733f-f1e9-4e9c-96c7-248486408b40"
}

Claim	Description
sub	Your client-ID
ext: authorized_scopes	The scopes the client was authorized for (this is an extension added for the admin-scope that was requested
ext: tenant_id	The tenant ID the client was authorized for
scp	Client scopes
exp, iat, iss, jti, nbf	Default claims

Integration Scopes

A token minted for an Integration Scope is deliberately minimal. It is intended to be handed to a downstream integration, so it proves the tenant and the user — and nothing else about them.

Access Token format

{
  "aud": [
    "803ad030-10a2-417a-bd19-7ad7ccc2dc9d-azmscope-partner-acme"
  ],
  "client_id": "803ad030-10a2-417a-bd19-7ad7ccc2dc9d",
  "exp": 1751192193,
  "ext": {
    "tenant_id": "d23e6db7-683b-4411-9ede-8ec040816de7"
  },
  "iat": 1751191533,
  "iss": "https://oidc.pie.azuma-health.tech",
  "jti": "6b1e2f70-3d55-4b58-9a2c-7c2c6f5f4a11",
  "nbf": 1751191533,
  "scp": [
    "partner-acme"
  ],
  "sub": "f09af826-8b73-46d6-80c5-57646e4d1384"
}

Claim	Description
aud	Exactly one audience, {applicationId}-azmscope-{scope}. A token minted for one integration cannot be replayed against another.
client_id	Your application-ID.
ext: tenant_id	The tenant ID — the only ext claim this token carries.
scp	The single configured scope the token was minted for.
sub	The user's account ID.
exp, iat, iss, jti, nbf	Default claims

What is absent is the point. There is no security_mode, no kind, no licenses, no permissions_app, no linked_authentications, and not even authorized_scopes. The token is never refreshable, and every ordinary azuma doa endpoint rejects it — only the introspection endpoint accepts it.

Health-ID ePA Integration

The reserved health-id-epa-integration scope mints the same minimal shape plus the user's KVNR binding. See Health-ID ePA Integration.

Access Token format

{
  "aud": [
    "803ad030-10a2-417a-bd19-7ad7ccc2dc9d-health-id-epa-integration"
  ],
  "client_id": "803ad030-10a2-417a-bd19-7ad7ccc2dc9d",
  "exp": 1751191833,
  "ext": {
    "authorized_scopes": [],
    "kvnr_hmac": "3sHwqS1Ob4ocO113n_CiTGvY4PGjxbfZ4fCixLbY4PE",
    "tenant_id": "d23e6db7-683b-4411-9ede-8ec040816de7"
  },
  "iat": 1751191533,
  "iss": "https://oidc.pie.azuma-health.tech",
  "jti": "a3f9c1d2-5e47-4b90-8c6a-2d1f7b3e5c88",
  "nbf": 1751191533,
  "scp": [
    "health-id-epa-integration"
  ],
  "sub": "f09af826-8b73-46d6-80c5-57646e4d1384"
}

Claim	Description
aud	{applicationId}-health-id-epa-integration. Note there is no azmscope marker — the ePA family is distinguishable by audience alone.
ext: authorized_scopes	Always empty. Present on this token family only; a configured-scope token omits it entirely.
ext: kvnr_hmac	A keyed hash of the user's Krankenversichertennummer, established through their Health-ID. The raw number is never in the token — it is an HMAC-SHA256 digest in unpadded Base64URL.
ext: tenant_id	The tenant ID.
scp	Always health-id-epa-integration.
exp, iat, iss, jti, nbf	Default claims. The lifetime is five minutes, and never longer than the token it was exchanged from.