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 rightWhat a connect does with it
workflow:age-checkCreates 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.
webhooksCreates or replaces a webhook endpoint at webhook_url and returns webhook_secret.
embed-originsAdds the storefront origins to the organization's embedding websites.
provisional-liveMay 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:readLets the key call GET /api/integrations/status.
workflows:readLets 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:writeThe 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-allWith 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

curl
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)

curl
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>"
  }'
JSON
{
  "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

curl
curl https://app-api.secuveri.com/api/integrations/status -H "x-api-key: $SECUVERI_API_KEY"
JSON
{
  "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:

curl
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.