End-User Access (SSO)

Some endpoints must act as the end user, not as your service account. For those you need an app token (app-auth). For backend integrations you mint one with the partner SSO endpoints — no login screen required.

When you need an app token

Feature	Example
Online Data	every /api/v1/delete-my-data* route
Self-service profile	GET /api/v1/account, PUT /api/v2/account/{id}
App watchlists	POST /api/v1/email-watchlist (no account id)
App alarms	GET /api/v1/alarms, GET /api/v2/alarms

Account administration and CRM {id} watchlist routes use the CRM token instead — see Account management.

Prerequisites

Your account manager provisions SSO credentials, separate from your CRM service account:

• client_id
• client_secret

The target account must already exist (created via CRM).

Direct token (recommended for M2M)

POST /api/v1/sso/token
Content-Type: application/json

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "email": "john.doe@example.com"
}

Response (200):

{ "token": "2|user-scoped-token..." }

Send Authorization: Bearer {token} on app routes. Use the same email the account was created with.

Authorization-code flow (browser redirect)

When the user lands in a web view, issue a one-time code and exchange it:

POST /api/v1/sso/code
Content-Type: application/json

{ "client_id": "your_client_id", "client_secret": "your_client_secret", "email": "john.doe@example.com" }

POST /api/v1/sso/login
Content-Type: application/json

{ "code": "one-time-code-from-previous-step" }

The exchange returns an access token just like /sso/token.

Using the app token

GET /api/v1/account
Authorization: Bearer {app_token}

Update the user's own profile:

PUT /api/v1/account
PUT /api/v2/account/{account_id}
POST /api/v2/account/password

Add an SSN via electronic ID (eID)

The end user can attach a verified national ID (SSN) to their own account by authenticating with an electronic ID provider (BankID, MitID, Finnish Trust Network, etc.) through Criipto. This is the only self-service way to set an SSN, and it is orchestrated with the app token — the SSN is written to the account the token belongs to.

This is the only way to backfill a missing SSN

On the CRM side an SSN can only be provided when the account is created. If the ssn was not supplied at creation, this eID flow is the only way to get it onto the account — there is no CRM/service-account route to add it later. The end user must prove ownership of the SSN via a trusted eID.

The shape is a standard OAuth-style redirect, in two steps. Use the same redirect_uri in both.

Step 1 — Start the eID session

Ask the gateway for a signed authorization URL, then redirect the user to it. Pass the redirect_uri the provider should return to, and optionally the eID method (see the table below).

POST /api/v1/criipto/ftn/auth
Content-Type: application/json

{
  "redirect_uri": "https://your-app.example.com/eid/callback",
  "method": "se.bankid.qr"
}

Response (200):

{
  "url": "https://your-tenant.criipto.id/oauth2/authorize?client_id=…&request=…&state=…",
  "action": "https://your-tenant.criipto.id/oauth2/authorize",
  "method": "GET",
  "params": { "client_id": "…", "request": "<signed-jwt>", "state": "<corr_id>" },
  "acr_values": "urn:grn:authn:se:bankid:another-device:qr",
  "corr_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Redirect the user to url. After they authenticate, the provider sends them back to your redirect_uri with ?code=…&state=….

Step 2 — Exchange the code for the SSN

Post the code (and the same redirect_uri) to the verify endpoint. This call carries the app token, so the gateway attaches the SSN to that account.

Nordic eIDs (FTN / BankID / MitID)

POST /api/v1/criipto/ftn/verify/ssn
Authorization: Bearer {app_token}
Content-Type: application/json

{
  "code": "<authorization-code-from-criipto>",
  "redirect_uri": "https://your-app.example.com/eid/callback",
  "method": "se.bankid.qr"
}

Criipto (OIDC code)

POST /api/v1/criipto/verify/ssn
Authorization: Bearer {app_token}
Content-Type: application/json

{ "code": "<authorization-code-from-criipto>" }

Response (200):

{ "ssn": "190001011234", "corr_id": "…" }

The Nordic FTN variant returns ssn plus a corr_id (the correlation id for support/tracing); the plain POST /api/v1/criipto/verify/ssn variant returns just { "ssn": "…" }.

Request fields

Field	Required	Notes
code	yes	One-time authorization code returned by the eID provider on the redirect back.
redirect_uri	yes (FTN)	Must exactly match the redirect_uri you used when starting the eID session.
method	no	The eID method (acr value) the user authenticated with — see the table below. Accepts a short alias or the full urn:grn:authn:… value.
state	no	Correlation id; echoed back as corr_id in the response and gateway logs.

The plain POST /api/v1/criipto/verify/ssn variant only needs code; the Nordic FTN variant additionally requires redirect_uri.

Supported method values (acr)

Country	Short alias	acr value
Sweden	se.bankid.same	urn:grn:authn:se:bankid:same-device
Sweden	se.bankid.qr	urn:grn:authn:se:bankid:another-device:qr
Finland	fi.all	urn:grn:authn:fi:all
Finland	fi.bank-id	urn:grn:authn:fi:bank-id
Finland	fi.mobile-id	urn:grn:authn:fi:mobile-id
Denmark	dk.mitid.low	urn:grn:authn:dk:mitid:low
Denmark	dk.mitid.substantial	urn:grn:authn:dk:mitid:substantial
Denmark	dk.mitid.high	urn:grn:authn:dk:mitid:high
Denmark	dk.mitid.business	urn:grn:authn:dk:mitid:business

Any full urn:grn:authn:<country>:… acr value is accepted as-is, so Norwegian BankID / Vipps (urn:grn:authn:no:bankid, urn:grn:authn:no:vipps) also work without a short alias. Which methods you offer per country is driven by your Criipto tenant configuration.

Rate limit

The eID routes are throttled to 10 requests per minute per client; exceeding that returns 429 Too Many Requests.

On success the SSN is saved to the account and monitoring follows the account's plan. The SSN must be valid for the account's country and unique — attaching an SSN already in use (or one that is blacklisted) returns a validation error.

App token only

These verify/ssn routes are app-scoped. A CRM service-account token cannot add an SSN this way — there is no CRM equivalent of the eID SSN flow.

Next step

Online Data — the flagship app-token flow.