# Connect with secuveri (partners)

For platform apps: the merchant clicks Connect with secuveri in your app, signs in to secuveri (or signs up), approves, and your server receives an API key, a published age-check workflow and a webhook signing secret. Nobody copies keys. It is an OAuth 2.0 authorization-code flow with PKCE (S256).

### Registering your app

secuveri staff register partner apps in the platform admin panel; write to us to get one. A registration has a client id, the exact redirect URIs (https, up to 10), what the issued API key may do (key scopes such as `sessions:write` and `results:read`), which setup rights a connect has, and the format of your platform's account identifiers (a regular expression from `^` to `$`, for example `^yourplatform:[0-9]{1,20}$`). You receive the client secret once; we keep only its SHA-256. When we rotate it, the old secret keeps working for 24 hours, unless it leaked: then it stops working at once. If we disable your app, merchants can no longer connect it, and connections that already exist keep their keys.

| Setup right | What a connect does with it |
| --- | --- |
| `workflow:age-check` | Creates two published workflows (or reuses them): the age check (age estimate first, ID as fallback), returned as `workflow_id`, and the ID check (always checks the ID), returned as `document_workflow_id`. |
| `webhooks` | Creates or replaces a webhook endpoint at `webhook_url` and returns `webhook_secret`. |
| `embed-origins` | Adds the storefront `origins` to the organization's embedding websites. |
| `provisional-live` | May give a not yet reviewed organization a live key (provisional access, below). Without it the key is `sk_test_` until secuveri approves the organization. |
| `status:read` | Lets the key call `GET /api/integrations/status`. |
| `workflows:read` | Lets the key call `GET /v1/workflows` to list the organization's published workflows of the key's environment, for example to let the merchant pick one in your app. |
| `workflows:write` | The key gets the `workflows:write` scope: it reads the workflow catalog and every workflow of its environment (drafts included), creates drafts, changes workflows and publishes them (see Build workflows with the API). A change to a published workflow applies to new verifications at once. The member approves it by name; a connection from before scopes existed never gets it. |
| `results:read-all` | With `results:read`, the key reads every verification of the organization in its environment (`GET /v1/verifications`, `GET /v1/verifications/{id}` and the signed result), not only the sessions it created. The consent page says so. The FINMA record and the webhook stay limited to your app's own sessions. |

### 1. Send the merchant to authorize

```shell
https://app.secuveri.com/connect/authorize
  ?client_id=your-app
  &redirect_uri=https://app.example.com/secuveri/callback
  &state=<opaque, returned unchanged>
  &code_challenge=<base64url SHA-256 of the verifier, 43 characters>
  &code_challenge_method=S256
  &account=<store or account identifier>
  &account_name=Demo%20Store
  &origins=https://store.example.com,https://www.example.ch
  &webhook_url=https://app.example.com/webhooks/secuveri
  &scope=sessions:write%20results:read%20workflow:age-check%20webhooks
```

- `client_id` and `redirect_uri` must match the registration exactly; otherwise secuveri shows an error and never redirects.
- `account`: the store or account identifier on your platform; it must match the format registered for your app, otherwise the merchant is returned to `redirect_uri?error=invalid_request&state=…`. `account_name`: shown on the consent page and in the connect email (up to 100 characters). `shop` and `shop_name` are older names for the same parameters and still work.
- `origins`: up to 5 https origins (no path) of the storefront; they are added to the organization's embedding websites. Only used with `embed-origins`.
- `webhook_url`: https, on the same host as `redirect_uri`. Required with `webhooks`, otherwise ignored.
- `scope` (optional): space-separated key scopes and setup rights, each one your app is registered for, with at least one key scope. Omit it to ask for everything your app is registered for. Anything else returns the merchant to `redirect_uri?error=invalid_scope&state=…`. The consent page lists what the merchant allows.
- Optional `email`, `name`, `company` and `website` fill in signup and the go-live form. They are defaults only.
- Optional `requester_name` and `requester_uri`, for an app that connects on behalf of other apps (such as an MCP server): the name of the app the member is connecting and the redirect URI that app gets its answer on. The consent page names that app, shows the host of `requester_uri` next to it and marks the app as unverified unless the host is a well-known one; a name that reads like a link or uses the name secuveri is not shown.
- Denied: `redirect_uri?error=access_denied&state=…`. Allowed: `redirect_uri?code=…&state=…`.

You MUST bind `state` to the signed-in user of your own app (the admin session of your app that clicked Connect), for example a random value stored in that session, and on the callback you MUST check that the `state` belongs to the current session before you exchange the code. Otherwise anyone can start a connect for their own account, send the consent link to a secuveri customer, and have that customer's approval connect the attacker's account to the customer's organization (consent phishing). Exchange a code only on the callback of the session that started it, and never for a code that arrives without a matching `state`.

### 2. Exchange the code (server to server)

```shell
curl -X POST https://app-api.secuveri.com/api/integrations/token \
  -H "content-type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "<code>",
    "client_id": "your-app",
    "client_secret": "<client secret>",
    "redirect_uri": "https://app.example.com/secuveri/callback",
    "code_verifier": "<the PKCE verifier>"
  }'
```

```shell
{
  "organization_id": "<organization id>",
  "organization_name": "Demo AG",
  "account": "<store or account identifier>",
  "environment": "production",
  "access": "provisional",
  "api_key": "sk_live_…",
  "workflow_id": "<workflow id>",
  "workflow_minimum_age": 18,
  "document_workflow_id": "<workflow id>",
  "document_workflow_minimum_age": 18,
  "webhook_secret": "whsec_…",
  "scope": "sessions:write results:read workflow:age-check webhooks"
}
```

`account` is the store or account the merchant approved: check that it is the one of the session that started the connect, and refuse the result otherwise. `scope` is what this connect allowed. The API key has exactly its key scopes. A field is `null` when its setup right was not allowed: `workflow_id`, `workflow_minimum_age`, `document_workflow_id` and `document_workflow_minimum_age` without `workflow:age-check`, `webhook_secret` without `webhooks`.

A code works once, for 10 minutes. Errors follow OAuth: 400 `invalid_request`, `invalid_grant` (unknown, used or expired code, wrong `redirect_uri` or verifier) or `unsupported_grant_type`; 401 `invalid_client`; 409 `plan_limit_reached` when the plan has no room for another active production workflow. Connecting the same account again revokes the previous key, keeps the workflows (as the merchant may have changed them; `workflow_minimum_age` and `document_workflow_minimum_age` are their current minimum ages; an account connected before the ID check existed gets it now) and gives the webhook a new secret (the old one signs for 24 more hours). Store the key and secret encrypted; secuveri cannot show them again.

### Access

- `approved`: the organization is approved for production; the key is live.
- `provisional`: not reviewed yet, but the company and the approving member passed sanctions screening. The key is live, limited to the monthly free verifications (50); after that, session creation answers 402 `provisional_limit_reached`. Provisional access lasts 30 days, or until the go-live request is decided if the merchant sent one by then; it is given once per organization, and a member gets it for one organization only. When secuveri approves the go-live request the limit disappears and the same key keeps working. If the request is rejected or secuveri ends provisional access, the key is revoked; when it lapses, live sessions are refused until approval.
- `sandbox`: screening was inconclusive, the organization is suspended, it already had provisional access, the approving member has it through another organization, or your app has no `provisional-live`. The key is `sk_test_`; reconnect after go-live for a live key.

### What your app can see

- The key reads results (`results:read`) only of the sessions it created; other verifications of the organization answer 404 and are left out of `GET /v1/verifications`. With `results:read-all` it reads the organization's verifications of its environment like an organization key: the plain summaries and the signed result, which carry no personal data. The FINMA record stays limited to the sessions it created.
- The key lists the organization's published workflows (`GET /v1/workflows`) only with `workflows:read` or `workflows:write`; without either the call answers 403. Drafts, and creating, changing or publishing workflows, need `workflows:write`.
- The webhook endpoint the connect set up receives events only for the sessions created with the connection's keys, also after a reconnect replaced the key.
- The organization's owners and admins get an email for every connect, naming your app, the store or account and who approved, with a link to disconnect.

### 3. Show the status in your app

```shell
curl https://app-api.secuveri.com/api/integrations/status -H "x-api-key: $SECUVERI_API_KEY"
```

```shell
{
  "access": "provisional",
  "environment": "production",
  "production_request": "pending",
  "free_allowance": {
    "limit": 50,
    "used": 12,
    "remaining": 38,
    "period_end": "2026-11-30T23:00:00.000Z"
  },
  "go_live_url": "https://app.secuveri.com/dashboard?go-live=1"
}
```

Read-only, with the key the connect issued (other keys get 401 `invalid_key`; a connect without `status:read` gets 403 `insufficient_scope`). The key's end date and IP addresses apply as on every API call. `production_request` is `none`, `pending`, `approved` or `rejected`; `go_live_url` opens the go-live form. The merchant can disconnect in Settings under Connected apps, which revokes the key, removes the webhook and removes the storefront addresses the connect added (unless another connected app uses them).

### 4. Revoke the key (server to server)

When the merchant disconnects in your app, uninstalls it, or a connect is abandoned on your side, revoke the key you received so it does not stay valid at secuveri:

```shell
curl -X POST https://app-api.secuveri.com/api/integrations/revoke \
  -H "content-type: application/json" \
  -d '{
    "client_id": "your-app",
    "client_secret": "<client secret>",
    "token": "<the API key>"
  }'
```

It follows OAuth 2.0 token revocation (RFC 7009) and authenticates like the token exchange (form or JSON body; during a secret rotation the previous secret works too). When `token` is the API key of one of your app's active connections, the key is revoked and the connection ends exactly as a disconnect in the dashboard: the webhook endpoint and the storefront addresses the connect added are removed, the workflows stay, and the organization's audit log names your app. The answer is 200 `{}` whether or not anything was revoked: an unknown or already revoked key, an organization's own key or another app's key is left alone. Errors: 400 `invalid_request` without `token`, 401 `invalid_client`, 429 after 30 calls a minute from one address. A revoked key can take up to 60 seconds to stop working.
