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

# Credentials API Overview

> Issue, verify, and revoke verifiable credentials for businesses, users, and AI agents with the Beltic Credentials API.

## What is the Credentials API?

The Beltic Credentials API issues cryptographically signed verifiable credentials that prove a fact about a subject — a business has been KYB'd, a user is over 21, an AI agent is authorized to spend up to \$500 on behalf of its owner. Credentials are signed JWT-VCs (W3C Verifiable Credentials 2.0) that any verifier can validate against Beltic's public keys without ever calling back to your servers.

Use cases include:

* Letting an authorized agent transact on a customer's behalf without sharing payment credentials.
* Proving to a counterparty that a business has been verified, without revealing the underlying KYB data.
* Onboarding flows where a user's identity check is reusable across services.

## Core Concepts

<CardGroup cols={2}>
  <Card title="Credential Types" icon="layer-group">
    Four discriminator-gated shapes: `business`, `user`, `agent_authorization`, and `outcome_attestation`. Each enforces its own claims schema at the API boundary.
  </Card>

  <Card title="Subject" icon="user-tag">
    The entity the credential is about — an organisation, person, agent, or document. The subject ID becomes part of the credential and is what verifiers index against.
  </Card>

  <Card title="Issuance" icon="signature">
    Beltic signs every credential with an ES256 key managed in AWS KMS. The signing key is published at `/.well-known/jwks.json`; any verifier can resolve it.
  </Card>

  <Card title="Revocation" icon="ban">
    Credentials are revocable via Status List 2021. Each credential is assigned a bit in your organisation's bitstring; revocation flips the bit, and verifiers detect it on their next check.
  </Card>
</CardGroup>

## Credential Lifecycle

<Steps>
  <Step title="Issue">
    Call `POST /v1/credentials` with a `credential_type`, a `subject`, and a `claims` object. Beltic validates the payload against the type-specific schema, allocates a status-list slot, signs the credential, and returns both the persisted record and the signed JWT-VC.
  </Step>

  <Step title="Verify">
    Anyone — your service, a partner, an external counterparty — can call `POST /v1/credentials/verify` with the JWT to confirm it's valid, unexpired, and not revoked. The verify pipeline runs a seven-step check that includes signature verification against the issuer's JWKS, claim validation, and a Status List 2021 lookup.
  </Step>

  <Step title="Revoke">
    Call `POST /v1/credentials/{id}/revoke` to mark a credential revoked. The credential's bit in the org bitstring is flipped; verifiers see the revocation on their next status-list fetch (Cache-Control max-age 60s).
  </Step>

  <Step title="Audit">
    Every issue, verify, revoke, and delete writes an immutable audit event. Query the audit log via `GET /v1/audit/events`, or subscribe to webhook streams to react to events as they happen.
  </Step>
</Steps>

## Authentication

All endpoints (except the public `/.well-known/*` paths and the public verify) require an API key passed as `X-Api-Key`. Keys are scoped by environment (`sk_staging_*` or `sk_production_*`) and carry a fixed set of permissions:

| Permission           | Required for                                                       |
| -------------------- | ------------------------------------------------------------------ |
| `credentials:write`  | Issue (`POST /v1/credentials`, `POST /v1/credentials/batch-issue`) |
| `credentials:read`   | List, get                                                          |
| `credentials:verify` | Verify                                                             |
| `credentials:revoke` | Revoke                                                             |
| `credentials:delete` | Delete                                                             |

API keys are created in the [Beltic Console](https://console.beltic.com). The raw key value is shown once at creation and never recoverable — store it securely.

## Flat JSON Responses

The Credentials API returns flat JSON, not JSON:API. Resources come back with their fields at the top level:

```json theme={null}
{
  "id": "cred_01HQXYZ...",
  "credential_id": "cred_01HQXYZ...",
  "credential_type": "agent_authorization",
  "subject": {
    "id": "agent_widgetcorp_assistant",
    "type": "agent",
    "name": "WidgetCorp Customer Assistant"
  },
  "claims": {
    "permissions": [
      {
        "resource_type": "wallet",
        "resource_id": "*",
        "actions": ["payment_authorize", "checkout"],
        "conditions": [{ "field": "transaction_amount", "op": "lte", "value": 50000 }]
      }
    ]
  },
  "signed_payload": "eyJhbGciOiJFUzI1NiIs...",
  "status": "active",
  "issued_at": "2026-05-21T10:30:00Z",
  "expires_at": "2026-08-19T10:30:00Z"
}
```

This is intentional — the API is designed for direct integration without an SDK and without per-language JSON:API parsers.

## Where to Next

<CardGroup cols={2}>
  <Card title="Issue a Credential" icon="plus" href="/guides/credentials/issuing-a-credential">
    Walk through `POST /v1/credentials` end-to-end, including credential-type-specific payloads.
  </Card>

  <Card title="Verify a Credential" icon="shield-check" href="/guides/credentials/verifying-a-credential">
    Verify a JWT-VC and understand the seven-step verify pipeline.
  </Card>

  <Card title="Revoke a Credential" icon="ban" href="/guides/credentials/revoking-a-credential">
    Revoke a credential and learn how the change propagates to verifiers.
  </Card>

  <Card title="Batch Issue" icon="layer-group" href="/guides/credentials/batch-issuing-credentials">
    Issue thousands of credentials in a single async job.
  </Card>
</CardGroup>