Skip to main content

​
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

EndpointPurpose
GET /.well-known/openid-configurationOIDC discovery document
GET /oauth/jwksEdDSA (Ed25519) public keys for token verification
POST /oauth/tokenToken endpoint — supports client_credentials, refresh_token, device_code, and CIBA grants
POST /oauth/revokeRevoke a token
POST /oauth/device/codeDevice authorization (for humans on CLIs)
GET /userinfoOIDC UserInfo

​
Per-action biometric approval (CIBA)

EndpointPurpose
POST /oauth/bc-authorizeStart a CIBA request — push prompt to user’s phone
POST /oauth/token with grant_type=urn:openid:params:grant-type:cibaPoll 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.
EndpointPurpose
POST /v1/x402/authorizeAuthorize an x402 USDC payment (on Base via EIP-3009)
GET /v1/x402/authorize/:idPoll for the signed EIP-3009 payload
POST /v1/mpp/authorizeAuthorize an MPP/Stripe SPT payment
GET /v1/mpp/authorize/:idPoll 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)

EndpointPurpose
GET /v1/vault/keysFetch the owner’s X25519 vault public key
POST /v1/vault/accessRequest access to a vault item — triggers biometric approval on the phone
GET /v1/vault/access/:idPoll 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

EndpointPurpose
POST /v1/checkout/initiateInitiate a merchant checkout (agent proposes, human approves)
GET /v1/checkout/:id/statusPoll 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

PatternWhat you wantEndpoints you’ll use
Drop-in biometric approval for your appCIBA/oauth/bc-authorize → /oauth/token
Gate an MCP server on biometricsCIBA + JWKSsame + /oauth/jwks
Accept agent payments on your APIx402 or MPP/v1/x402/authorize or /v1/mpp/authorize
Use BKey as your OIDC IdPFull OIDCDiscovery + all /oauth/* endpoints
Read a vault secret from your agentE2EE vault/v1/vault/keys → /v1/vault/access → poll

​
See also