> ## Documentation Index
> Fetch the complete documentation index at: https://bkey.id/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrate BKey

> BKey is a standards-compliant OIDC issuer. Point any OIDC-aware auth library at our discovery URL and you can use BKey for CIBA biometric approval, agent payments (x402 + MPP), and standard OAuth 2.1 login — no SDK required.

# 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:

```http theme={null}
GET https://api.bkey.id/.well-known/openid-configuration
```

Most OIDC libraries auto-configure from this URL. See the [OIDC discovery endpoint reference](/docs/api-reference/oauth/oidc-discovery).

## Endpoints

### Standard OAuth 2.1 / OIDC

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

### Per-action biometric approval (CIBA)

| Endpoint                                                                                                       | Purpose                                            |
| -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| [`POST /oauth/bc-authorize`](/docs/api-reference/oauth/ciba-backchannel-authorize)                                  | Start a CIBA request — push prompt to user's phone |
| [`POST /oauth/token`](/docs/api-reference/oauth/token-endpoint) 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](/docs/guides/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](/docs/authentication/ciba) 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](/docs/guides/x402-payments) for the auto-detect flow and cost comparison.

### Vault (E2EE secrets)

| Endpoint                                                                   | Purpose                                                                   |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| [`GET /v1/vault/keys`](/docs/api-reference/vault/list-vault-keys)               | Fetch the owner's X25519 vault public key                                 |
| [`POST /v1/vault/access`](/docs/api-reference/vault/request-vault-access)       | Request access to a vault item — triggers biometric approval on the phone |
| [`GET /v1/vault/access/:id`](/docs/api-reference/vault/get-vault-access-status) | 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](/docs/guides/encryption) for the full envelope (X25519 ECDH + AES-256-GCM).

### Checkout

| Endpoint                                                                     | Purpose                                                       |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------- |
| [`POST /v1/checkout/initiate`](/docs/api-reference/checkout/initiate-checkout)    | Initiate a merchant checkout (agent proposes, human approves) |
| [`GET /v1/checkout/:id/status`](/docs/api-reference/checkout/get-checkout-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](/docs/authentication/device-authorization).
* **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()`](https://www.npmjs.com/package/@bkey/node). 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 |

## See also

* [Authentication overview](/docs/authentication/overview) — all grant types at a glance
* [CIBA](/docs/authentication/ciba) — biometric approval, with one-line SDK pattern
* [Client credentials](/docs/authentication/client-credentials) — agent auth grant
* [CLI authentication](/docs/authentication/device-authorization) — human + agent credential flows
* [Agent payments](/docs/guides/x402-payments) — x402 + MPP auto-detection
* [Encryption](/docs/guides/encryption) — what's protected at each step
* [API Reference](/docs/api-reference/overview) — every endpoint documented