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

# OCSP

> GET /v1/ocsp/:jti — signed passport status check.

## `GET /v1/ocsp/:jti`

Returns the revocation status of a passport, identified by its `jti`. The response is signed with the company's Ed25519 key, so verifiers can confirm the response is authentic. Requires authentication.

Responses are cached for 5 minutes (`Cache-Control: public, max-age=300`). Use this endpoint in verifiers that cannot hold the full revocation list but need stronger guarantees than offline-only verification.

### Path parameters

| Parameter | Type     | Description                               |
| --------- | -------- | ----------------------------------------- |
| `jti`     | `string` | The UUID from the passport's `jti` claim. |

### Response `200` — valid passport

| Field         | Type      | Description                                           |
| ------------- | --------- | ----------------------------------------------------- |
| `jti`         | `string`  | The passport ID checked.                              |
| `companyId`   | `string`  | The company that issued this passport.                |
| `status`      | `"valid"` | The passport has not been revoked.                    |
| `checkedAt`   | `string`  | ISO 8601 timestamp of this check.                     |
| `caPublicKey` | `string`  | Ed25519 SPKI PEM. Used to verify `signature`.         |
| `signature`   | `string`  | Ed25519 signature over the response data (base64url). |

### Response `200` — revoked passport

| Field         | Type        | Description                                           |
| ------------- | ----------- | ----------------------------------------------------- |
| `jti`         | `string`    | The passport ID checked.                              |
| `companyId`   | `string`    | The company that issued this passport.                |
| `status`      | `"revoked"` | The passport has been revoked.                        |
| `checkedAt`   | `string`    | ISO 8601 timestamp of this check.                     |
| `revokedAt`   | `string`    | ISO 8601 timestamp when revocation occurred.          |
| `reason`      | `string`    | Present if a reason was recorded.                     |
| `caPublicKey` | `string`    | Ed25519 SPKI PEM.                                     |
| `signature`   | `string`    | Ed25519 signature over the response data (base64url). |

### Verifying the OCSP response signature

The `signature` covers the response data object (excluding `caPublicKey` and `signature` themselves). To verify:

1. Remove `caPublicKey` and `signature` from the response object.
2. Canonicalize the remaining object (sort keys recursively, then JSON-stringify).
3. Compute SHA-256 of the canonical string.
4. Verify the Ed25519 signature over that hash using the `caPublicKey`.

### Example

```bash theme={null}
curl -s http://localhost:3000/v1/ocsp/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $API_KEY"
```

Valid passport:

```json theme={null}
{
  "jti": "550e8400-e29b-41d4-a716-446655440000",
  "companyId": "acme",
  "status": "valid",
  "checkedAt": "2026-01-01T00:05:00.000Z",
  "caPublicKey": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n",
  "signature": "vdv-nC4o..."
}
```

Revoked passport:

```json theme={null}
{
  "jti": "550e8400-e29b-41d4-a716-446655440000",
  "companyId": "acme",
  "status": "revoked",
  "checkedAt": "2026-01-01T02:00:00.000Z",
  "revokedAt": "2026-01-01T01:00:00.000Z",
  "reason": "agent compromised",
  "caPublicKey": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n",
  "signature": "Xt8q1R7m..."
}
```