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

# API Overview

> BKey API — base URL, authentication, response format, and error handling.

<Warning>
  The BKey API is in **active development**. Endpoints and schemas may change without notice.
</Warning>

## Base URL

```
https://api.bkey.id
```

## Authentication

Most endpoints require a Bearer token obtained via OAuth 2.1 client credentials or CIBA:

```http theme={null}
Authorization: Bearer <access_token>
```

Merchant-facing endpoints use a separate merchant API key scheme:

```http theme={null}
Authorization: Bearer mk_live_...
```

See [Authentication Overview](/docs/authentication/overview) for details.

## Response format

Successful responses return JSON:

```json theme={null}
{
  "id": "chk_abc123",
  "status": "pending",
  "amount": 9.99
}
```

## Error format

Errors return an appropriate HTTP status with structured details:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "invalid_argument",
    "message": "Amount is required"
  }
}
```

## HTTP status codes

| Code  | Meaning                                    |
| ----- | ------------------------------------------ |
| `200` | Success                                    |
| `201` | Created                                    |
| `400` | Validation error — check request body      |
| `401` | Unauthorized — missing or invalid token    |
| `403` | Forbidden — insufficient scopes            |
| `404` | Resource not found                         |
| `409` | Conflict — duplicate or concurrent request |
| `429` | Rate limited                               |
| `5XX` | Server error                               |

## OpenID Connect discovery

```
GET /.well-known/openid-configuration
```

Returns the OIDC discovery document with all supported endpoints, grant types, and signing algorithms.

## Signing keys

```
GET /oauth/jwks
```

Returns the JSON Web Key Set for verifying BKey-issued JWTs. Keys use EdDSA (Ed25519).