Skip to main content
Scrive logoeID Hub Documentation

API-only Usage

For headless flows or when your application provides its own UI, you can drive the API directly without the Hub frontend. The start-and-poll pattern differs per provider. Each section below describes the exact steps.

info

API-only mode is not supported by all providers. Danish MitID cannot be used without the Hub frontend, as the MitID UI client must be hosted by a broker on a mitid.dk subdomain.

Swedish BankID​

  1. Create a transaction.
  2. Start the transaction, setting endUserIP to the end user's IP address.
  3. Extract autoStartToken from the response and use it to launch your custom UI. See the BankID autostart documentation for details. Note that BankID's redirect parameter is separate from the redirectUrl you set on transaction creation.
  4. Poll transaction status and completion data.
warning

SE BankID does not allow more than one active transaction per personal number. If you specify the end user's personal number at creation or start, cancel the transaction before starting a new one for the same person, or wait for it to expire (fixed at 3 minutes by SE BankID).

Norwegian BankID, Finnish FTN, German Verimi, Dutch iDIN, Belgian Itsme, Digidentity and Scrive QES​

  1. Create a transaction.
  2. Start the transaction and extract authUrl or signUrl from the response.
  3. Send the user to that URL via redirect or popup, not an iframe.
  4. Query transaction completion data once your redirectUrl is called.

Danish MitID​

API-only usage is not possible for MitID. The MitID UI client must be hosted by the broker on a mitid.dk subdomain. Use the eID Hub Frontend instead.

SMS OTP​

  1. Create a transaction.
  2. Start the transaction. Provide msisdn either at creation or at start. If provided at creation, it cannot be changed at start.
  3. Collect the OTP from the user via your own UI and validate it via the SMS-OTP check endpoint.
  4. Query transaction data once the OTP is confirmed valid, or when the number of attempts remaining reaches 0.

Onfido​

Onfido API-only requires embedding the Onfido Web SDK in your page.

  1. Create a transaction, specifying referrerUrlPatternForSdk.
  2. Start the transaction. Extract sdkToken and initialise the Onfido SDK with it.
  3. Once the SDK completes, call the "Continue with Onfido process" endpoint.
  4. Poll transaction status and completion data.

Freja eID​

  1. Create a transaction.
  2. Start the transaction. If userInputInfo is left empty, extract authRef from the response and use it in your custom UI. See Freja's troubleshooting guide for implementation details. If you always preset userInputInfo, no UI is needed.
  3. Poll transaction status and completion data.

SmartID​

  1. Create a transaction.
  2. Start the transaction and extract verificationCode from the response. Display this code to the user so they can compare it with the code shown in the SmartID app.
  3. Poll transaction status and completion data.

Multi-Auth Selection (MAS)​

MAS lets the end user choose from a set of eID provider options within a single transaction. API-only usage follows the same per-provider steps above, with an extra step to select the option.

  1. Create a MAS transaction via POST /mas/new, specifying masOptions (an array of provider/method combinations) and redirectUrl.
  2. Start the transaction via POST /mas/{transaction_id}/start, providing masSelectedOptionId and any provider-specific parameters required for the chosen option.
  3. Continue the provider-specific flow for the selected option (see the relevant section above).
  4. Poll transaction completion data via GET /mas/{transaction_id}.

See the Multi-Auth Selection guide for full details.