Integrate BKey as your authorization layer

You do not need our SDK to use BKey. We’re a standards-compliant OAuth 2.1 / OIDC / CIBA (RFC 8958) provider — any auth library that speaks those protocols can talk to BKey directly. Use BKey when you want any of the following in your own app or server:

Per-action biometric approval — CIBA: push a consent prompt to a user’s phone, get back a signed JWT proving they approved the specific action.
Agent payments — x402 (USDC on Base, via EIP-3009) and MPP (Stripe Shared Payment Tokens). Your 402-serving code calls BKey’s authorize endpoints; BKey handles spending limits, biometric approval, and signing.
Standard OAuth 2.1 / OIDC — client_credentials, device_authorization, token exchange, revocation, JWKS.

Discovery

Start here. The discovery document describes every endpoint, grant type, and supported algorithm BKey offers:

GET https://api.bkey.id/.well-known/openid-configuration

Most OIDC libraries auto-configure from this URL. See the OIDC discovery endpoint reference.

Endpoints

Standard OAuth 2.1 / OIDC

Endpoint	Purpose
`GET /.well-known/openid-configuration`	OIDC discovery document
`GET /oauth/jwks`	EdDSA (Ed25519) public keys for token verification
`POST /oauth/token`	Token endpoint — supports `client_credentials`, `refresh_token`, `device_code`, and CIBA grants
`POST /oauth/revoke`	Revoke a token
`POST /oauth/device/code`	Device authorization (for humans on CLIs)
`GET /userinfo`	OIDC UserInfo

Per-action biometric approval (CIBA)

Endpoint	Purpose
`POST /oauth/bc-authorize`	Start a CIBA request — push prompt to user’s phone
`POST /oauth/token` with `grant_type=urn:openid:params:grant-type:ciba`	Poll for the signed approval token

Your app calls /oauth/bc-authorize with a login_hint (the user’s DID), a scope, and a human-readable binding_message. The user gets a push notification, approves with biometrics, and your app’s poll returns an EdDSA-signed JWT scoped to that specific action. Typical integration shapes:

MCP servers — gate every tool call on CIBA; verify the returned token with @bkey/node or any JWKS-aware JWT library. See MCP integration.
Admin consoles / deploy pipelines — require a fresh biometric approval before destructive operations (deploy, rollback, db drop, refund).
Any app with a “confirm with your phone” pattern — replace the soft click with a cryptographically bound, replay-resistant attestation.

See the CIBA guide for the full protocol and the one-line SDK pattern.

Agent payments (x402 + MPP)

For agents and 402-serving APIs. BKey handles spending limits, biometric approval (via CIBA above), and payment signing — your agent or server never touches the user’s keys.

Endpoint	Purpose
`POST /v1/x402/authorize`	Authorize an x402 USDC payment (on Base via EIP-3009)
`GET /v1/x402/authorize/:id`	Poll for the signed EIP-3009 payload
`POST /v1/mpp/authorize`	Authorize an MPP/Stripe SPT payment
`GET /v1/mpp/authorize/:id`	Poll for the SPT credential

Auto-detection is built in — the CLI proxy, skill, and SDK inspect the 402 response headers and pick the right protocol. If you’re building a gateway or SDK of your own, you can call these endpoints directly. See the agent payments guide for the auto-detect flow and cost comparison.

Vault (E2EE secrets)

Endpoint	Purpose
`GET /v1/vault/keys`	Fetch the owner’s X25519 vault public key
`POST /v1/vault/access`	Request access to a vault item — triggers biometric approval on the phone
`GET /v1/vault/access/:id`	Poll the access request; ciphertext is returned in `e2eeCiphertext`

Vault values are end-to-end encrypted between your process and the user’s phone. The server never sees plaintext. See encryption for the full envelope (X25519 ECDH + AES-256-GCM).

Checkout

Endpoint	Purpose
`POST /v1/checkout/initiate`	Initiate a merchant checkout (agent proposes, human approves)
`GET /v1/checkout/:id/status`	Poll for completion

Registering your app / agent

Before you can hit most of these endpoints, you need a client_id + client_secret:

For agents — run bkey auth setup-agent --save from a logged-in CLI. BKey pushes a one-time approval to your phone for the scopes you want, then issues the credentials. Details in CLI authentication.
For apps that act as an OIDC client on behalf of other users — reach out; we’ll provision a client for you.

Token format

All tokens BKey issues are JWTs signed with EdDSA (Ed25519):

header:  { "alg": "EdDSA", "kid": "<key id>", "typ": "JWT" }
payload: {
  "iss": "https://api.bkey.id",
  "sub": "did:bkey:...",
  "aud": "your-client-id",
  "scope": "approve:deploy",
  "jti": "<unique>",
  "iat": ..., "exp": ...
}

Verify with any JWKS-aware JWT library or @bkey/node’s verifyToken(). The library pins alg: EdDSA, enforces scope, and returns null-prototype claims. No HS256 confusion, no alg: none.

Integration patterns

Pattern	What you want	Endpoints you’ll use
Drop-in biometric approval for your app	CIBA	`/oauth/bc-authorize` → `/oauth/token`
Gate an MCP server on biometrics	CIBA + JWKS	same + `/oauth/jwks`
Accept agent payments on your API	x402 or MPP	`/v1/x402/authorize` or `/v1/mpp/authorize`
Use BKey as your OIDC IdP	Full OIDC	Discovery + all `/oauth/*` endpoints
Read a vault secret from your agent	E2EE vault	`/v1/vault/keys` → `/v1/vault/access` → poll

Getting Started

Authentication

Guides

Integrate BKey

Integrate BKey as your authorization layer

Discovery

Endpoints

Standard OAuth 2.1 / OIDC

Per-action biometric approval (CIBA)

Agent payments (x402 + MPP)

Vault (E2EE secrets)

Checkout

Registering your app / agent

Token format

Integration patterns

See also

​Integrate BKey as your authorization layer

​Discovery

​Endpoints

​Standard OAuth 2.1 / OIDC

​Per-action biometric approval (CIBA)

​Agent payments (x402 + MPP)

​Vault (E2EE secrets)

​Checkout

​Registering your app / agent

​Token format

​Integration patterns

​See also

Integrate BKey as your authorization layer

Discovery

Endpoints

Standard OAuth 2.1 / OIDC

Per-action biometric approval (CIBA)

Agent payments (x402 + MPP)

Vault (E2EE secrets)

Checkout

Registering your app / agent

Token format

Integration patterns

See also