Authentication

Every WRL request that creates or reads captures requires a bearer token. This guide covers how to use your API key, what scopes control access, and how operators manage keys.

Using Your API Key

Set your API key as a bearer token in the Authorization header on every request.

curl https://api.webresourceledger.com/v1/captures \
  -H "Authorization: Bearer YOUR_API_KEY"

Replace YOUR_API_KEY with your actual key. Keys issued by the admin API are prefixed with wrl_live_. Keep your key secret -- anyone who has it can submit captures and read your capture history.

Scopes

Every API key is granted one or more scopes that control which endpoints it can reach.

Because capture implies read, a key with capture scope can do everything a read-only key can do plus submit new captures.

Endpoint scope requirements

Note: Artifact URLs and the verification endpoint are unauthenticated by design. The capture ID itself acts as the access secret -- treat it like a password. Anyone with the ID can view the capture and all its artifacts.

Managing API Keys (Operators)

If you operate a WRL deployment, you manage API keys through the admin API. Admin endpoints require a separate admin credential -- a secret key set by the operator during deployment. This credential is distinct from tenant API keys and does not grant capture or read access.

Create a key

curl -X POST https://api.webresourceledger.com/v1/admin/keys \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "acme-corp",
    "scopes": ["capture"],
    "name": "ci-pipeline"
  }'

{
  "key": "wrl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789abcdefghij",
  "keyHash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "tenantId": "acme-corp",
  "scopes": ["capture"],
  "name": "ci-pipeline",
  "createdAt": "2026-03-22T12:00:00.000Z",
  "warning": "Store this key now. It cannot be retrieved after this response."
}

The raw key is shown exactly once. Store it immediately -- it cannot be retrieved later. The keyHash is the opaque identifier returned at creation time; you will use it if you need to revoke this key.

Request fields:

List keys

curl https://api.webresourceledger.com/v1/admin/keys \
  -H "Authorization: Bearer YOUR_ADMIN_KEY"

{
  "keys": [
    {
      "keyHash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
      "tenantId": "acme-corp",
      "scopes": ["capture"],
      "name": "ci-pipeline",
      "createdAt": "2026-03-22T12:00:00.000Z",
      "createdBy": "admin"
    }
  ]
}

The list never includes raw key values. Use keyHash values to identify keys for revocation.

Revoke a key

Pass the keyHash from the creation response (or the list endpoint) to revoke a key immediately.

curl -X DELETE \
  https://api.webresourceledger.com/v1/admin/keys/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 \
  -H "Authorization: Bearer YOUR_ADMIN_KEY"

Revocation is immediate and idempotent. Revoking a key that is already revoked returns the same response without error.

Key rotation pattern

To rotate a key without downtime:

1. Create a new key for the same tenant and scope.
2. Distribute the new key to all systems that use the old one.
3. Verify the new key is working in production.
4. Revoke the old key using its keyHash.

This order ensures access is never interrupted. The brief window where both keys are valid is safe -- old captures remain accessible regardless of which key created them.

curl -X POST https://api.webresourceledger.com/v1/captures \
  -H "Authorization: Bearer YOUR_CAPTURE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'