Zum Hauptinhalt springen

FAQ

Frequently asked questions from teams integrating azuma mimoto. Each answer links to the full documentation for the topic — this page is a fast-answer layer on top of it, not a replacement.

Getting Started & Registration​

How do I get access to the Developer Portal?​

You need an azuma doa account assigned to a Developer Tenant. The easiest way is to contact us and we'll create the Developer Tenant and send an invitation. On the lower (PIE) environment, you can also create a new Developer Tenant yourself. See Developer Portal for details.

What's the difference between a Simulation and a full Gesundheits-ID Relying Party?​

Simulation lets you evaluate azuma mimoto against a simulated federation flow at no cost — ideal for initial evaluation. Gesundheits-ID is the full integration, where your Application is registered with the gematik Federation Master. See Developer Portal.

How long does Federation Master registration take, and can azuma send it on our behalf?​

Registration per Environment (TU/RU/PU) can take several business days. azuma can send the registration email on your behalf for the lower environments (TU/RU). A PROD registration additionally requires prior admission tests by gematik in the lower environments, plus further DiGA identification data. See Overview.

Can I create or modify a Relying Party myself?​

No — a Relying Party can currently only be created or modified by azuma, since every change needs to be synchronized with the Entity Statement within the federation. Application configuration, on the other hand, can be done by you via the Developer Portal.

Integration Approach​

Should I implement the OIDC flow manually?​

We'd advise against it — well-tested and hardened OIDC libraries are available for most languages and frameworks, and manual implementations have security implications on token storage and handling. See Overview.

What's the difference between Proxy Mode and Full Mode token storage?​

Proxy Mode: azuma mimoto doesn't store tokens at all (only some claims are stored encrypted during login and removed afterward) — each token retrieval requires a full user login. Full Mode: tokens are stored encrypted for their validity period, so the Application can request a token within that window without triggering a full login. See Overview.

Why does mimoto issue its own tokens instead of passing through the original IDP tokens?​

The Application doesn't know which Identity Provider was chosen and has no easy way to fetch its public signing keys to validate the tokens. mimoto Tokens can be verified uniformly, ensuring a fully secure data exchange chain. If you need the original IDP tokens for a specific reason, they can still be included as claims — see Overview.

Mobile / App-to-App Flow​

Why shouldn't my app auto-follow the auth redirect in the App-to-App flow?​

Automatically following the redirect would call the IDP deep link prematurely, which can lead to errors. Since disabling automatic redirect handling isn't always possible (e.g. with fetch), request the JSON response format instead via the response_format=json query parameter. See Overview.

How can I test the App-to-App flow without a real gematik authenticator?​

azuma provides dedicated authenticator test apps for Android and iOS to support integration testing. Contact us for access. See Overview.

Tokens & Claims​

The sub claim collides across identity providers — how do I get a stable, unique user ID?​

The sub claim is only unique within a single Identity Provider, not across all of them. Either concatenate the iss and sub claims yourself, or use the ext-mimoto-original-sub-unique claim, which already contains that concatenation. See Overview.

How do I verify that a token was actually issued by azuma mimoto?​

Use the token introspection endpoint. It requires a dedicated Introspection Client, which you can create yourself in the mimoto dashboard under Applications. Introspection works for both Access Token and ID Token. See Overview.

How can I validate client IDs across multiple DiGA applications centrally?​

Use the Client Validation API. It requires a client_credentials token from a dedicated "Validation Application" in your Relying Party — that one client then works across all of your Relying Parties. See Client Validation.

Errors & Troubleshooting​

What error handling modes can I configure per Application?​

  • Default: the integrated error UI screen of azuma mimoto is displayed.
  • Redirect to Auth: errors are redirected to the Redirect-URL from the Auth-Request (redirect-url?error=*error*).
  • Redirect to Custom: errors are redirected to a custom URL configured for the Application (custom-url?error=*error*).

See Error Handling.

What format do azuma mimoto API errors use?​

JSON wherever possible, in the shape {"error": "...", "error_description": "...", "error_uri": "..."}. Standard error codes follow RFC 6749 §4.2.2.1 (access_denied, invalid_request, invalid_scope, server_error, temporarily_unavailable, unauthorized_client, unsupported_response_type). See Error Handling.

My App-to-App deep-link error doesn't match what I expected — why?​

The App-to-App deep-link error scenario isn't yet specified by gematik. In practice, IDPs may return an error code directly in the deep link call (e.g. *redirect-deep-link*?error=access_denied...). Since this isn't standardized yet, we'd advise showing a generic error message for these cases. See Error Handling.

RU Testing with the gematik IDP​

Where do I configure the X-Authorization header for testing with the gematik IDP?​

Not in the azuma dashboard — azuma already injects the header on the backend side. You only need it additionally where the request goes directly from the browser or authenticator to gematik:

  • Web: via a browser plugin that can set headers (e.g. ModHeader).
  • Mobile: as the X-Authorization key in the gematik Authenticator (GSIA).

Background: on login, azuma opens the Pushed Authorization Request (PAR) as a gematik URL in the browser. For that URL to be reachable, the header must be injected there — only the browser or the authenticator can do this.

Where do I get the X-Authorization header?​

The header is provided by gematik — request it via diga [at] gematik.de. It's used in the Pushed Authorization Request sent by the backend and configured in the gematik Authenticator (GSIA). You can test it against the entity statement:

curl -H "X-Authorization: <HEADER>" \
  https://gsi-ref.dev.gematik.solutions/.well-known/openid-federation

On the gematik login page I always get the same test user. How do I select a different account?​

Via the KVNR on the gematik login page. The KVNR corresponds to the claims:id field in the versicherte.gesundheitsid.json file of the gematik reference IDP. Change the KVNR to select the desired test user.