OAuth client registration

Register in the account UI

Sign in, choose the owning BAP identity, and open OAuth Clients under /account/{bapId}/oauth-clients. Give the integration a recognizable name and register its exact callback URLs. The application needs a dedicated member signing key; register its compressed public key as accountPubkey and keep the WIF only on the application backend.

The client ID identifies an application. It is not a secret, a user ID, or a BAP identifier. Do not invent an unregistered value in a production authorize URL.

Management API

POST /api/oauth-clients requires a Better Auth session and ownership of ownerBapId:

{
  "clientId": "my-application",
  "ownerBapId": "owned-bap-id",
  "name": "My application",
  "redirectUris": ["https://your-app.example/auth/sigma/callback"],
  "accountPubkey": "compressed-secp256k1-public-key"
}

Required fields are clientId, ownerBapId, name, redirectUris, and accountPubkey. Client IDs use letters, numbers, underscores, and hyphens; conflicts return 409. Optional presentation fields include icon, uri, logoUri, tosUri, policyUri, contacts, and themeOrigin.

GET /api/oauth-clients?clientId=… exposes public client metadata. Authenticated listing returns owned clients as supported by the query. PUT and DELETE /api/oauth-clients/{clientId} manage an owned client. Do not assume public metadata access grants write access.

The account UI exposes /account/{bapId}/oauth-clients/{clientId}/analytics, backed by the owned-client analytics API. These are observed server records, not a universal end-user tracking or billing meter.

Dynamic registration and agents

Better Auth advertises POST /api/auth/oauth2/register. Its schema uses standard OAuth registration names such as redirect_uris; that is a different endpoint from Sigma's camelCase management API.

The current Sigma authorization-code/refresh hook additionally requires a registered accountPubkey and X-Auth-Token. Generic DCR and the agent register_oauth_client capability do not automatically supply this key. Complete supported client configuration before attempting the hosted signed exchange. Do not advertise DCR-only registration as a finished browser integration.

Release checklist

Use distinct staging callbacks and credentials. Verify redirect matching, registered-key matching, PKCE/state failures, refresh, consent, and application session creation before shipping. Changing client metadata does not rotate a user's identity keys. Do not remove a production client merely to fix a staging callback.