# Sign in with secuveri

Let people sign in to your website or app with the secuveri credential in their wallet instead of a password or a new verification. secuveri is an OpenID Connect provider: your OIDC library sends the person to secuveri, they scan a QR code (or tap Open wallet on their phone) and share their credential, and your app receives an `id_token` with a pseudonymous user ID and only the details its scopes allow. The wallet discloses nothing else (selective disclosure), and your app never sees a document.

### 1. Create an application

In Settings, under Sign in with secuveri. Choose Server for a backend that can keep a secret (`client_secret_basic` or `client_secret_post`), or App or single-page for a mobile or browser app (no secret, PKCE only; it may register a reverse-domain scheme such as `com.example.app:/oidc`). Register every redirect URI exactly: it is compared character for character, including path and query, with no wildcards. Pick the scopes the application may ask for. The client ID is shown at once and the secret only once; rotating the secret replaces it immediately, and deleting the application stops its tokens at once.

### 2. Point your OIDC library at the discovery document

```shell
curl https://api-verify.secuveri.com/.well-known/openid-configuration
```

| Endpoint | Path |
| --- | --- |
| Issuer | `https://api-verify.secuveri.com` |
| Authorization | `/oidc/authorize` (GET or form POST) |
| Token | `/oidc/token` |
| UserInfo | `/oidc/userinfo` (Bearer access token) |
| JWKS | `/oidc/jwks` (ES256; keys are rotated, select by `kid`) |

### 3. Send the person to the authorization endpoint

Authorization code flow only (`response_type=code`), with PKCE `S256` required for every application. Send a fresh `state` and `nonce` and check both when the person comes back. `ui_locales` (`en`, `de`, `fr`, `it`) picks the language of the sign-in page.

```shell
https://api-verify.secuveri.com/oidc/authorize
  ?response_type=code
  &client_id=svc_…
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Fauth%2Fcallback
  &scope=openid%20profile%20age_over_18
  &state=af0ifjsldkj
  &nonce=n-0S6_WzA2Mj
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
```

The person comes back to the redirect URI with `code`, your `state` and `iss` (RFC 9207), or with `error` (`access_denied` when they cancel, `invalid_scope` for a scope the application may not use, `login_required` for `prompt=none`: there is no secuveri session to reuse). An unknown client or a redirect URI that is not registered shows an error page and never redirects.

### 4. Exchange the code

```shell
curl -X POST https://api-verify.secuveri.com/oidc/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri=https://app.example.com/auth/callback \
  -d code_verifier="$CODE_VERIFIER"
```

```shell
{
  "access_token": "…",
  "token_type": "Bearer",
  "expires_in": 600,
  "id_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6Ii4uLiIsInR5cCI6IkpXVCJ9…",
  "scope": "openid profile age_over_18"
}
```

A code is valid for 60 seconds and works once; using it again is refused and revokes the access token it was exchanged for. An app without a secret sends `client_id` in the form instead of the Basic header. Tokens last 10 minutes; there are no refresh tokens: sign the person in again when you need fresh claims. Verify the `id_token` like any OIDC token: signature against the JWKS, `iss`, `aud` (your client ID), `exp` and your `nonce`.

### Scopes and claims

| Scope | Claims |
| --- | --- |
| `openid` (required) | `sub`: a pseudonymous ID for this person and this application. It stays the same for the person at your application and differs between applications, so two applications cannot match their users through it. It is derived with a secret key from the credential's holder identifier (the portrait hash of a `secuveri-passport`, the document number hash of a `secuveri-kyc-attestation`) and is never a document number. |
| `profile` | `given_name`, `family_name` |
| `birthdate` | `birthdate` (`YYYY-MM-DD`) |
| `age_over_18` | `age_over_18` (`true` or `false`), without the birth date |
| `verified` | `verification_level` (for example `full_kyc_nfc` when the document chip was read) and `verified_at`, when secuveri verified the person |

The claims are in the `id_token` and from the UserInfo endpoint. A claim the credential does not carry is left out rather than guessed. Accepted credentials are secuveri's own (`secuveri-passport`, `secuveri-kyc-attestation`), checked like any presentation: signed by secuveri's issuer, not expired, not revoked or suspended on its status list, and presented by the device it was issued to, for this sign-in.

Because `sub` comes from the credential that was presented, a person who holds both a `secuveri-passport` and a `secuveri-kyc-attestation` gets a different `sub` depending on which one they share. We recommend that your application uses one credential type: tell your users which one to share, or link accounts on your side by another attribute, so returning users are always recognised.
