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

# Authentication

> vck_ API keys, scope vocabulary, and rotation procedure.

The Partner API uses long-lived API keys for authentication. Each key carries an explicit set of scopes that authorize specific endpoints.

## Key format

Keys are issued in two halves joined by a literal dot:

```
vck_<key_id>.<secret>
```

* `vck_` — fixed prefix, identifies this as a VantageClaw Partner key.
* `<key_id>` — public identifier. Safe to log and reference in support tickets.
* `<secret>` — high-entropy secret. **Never log, never commit, never share.**

Pass the full token in the `Authorization` header on every request:

```http theme={null}
Authorization: Bearer vck_test_REPLACE_ME.your_secret_half_here
```

The secret half is returned **once** in the key-creation response. It is not recoverable — if lost, the key must be revoked and a new one issued.

## Scopes

A key's scopes determine which endpoints it can call. Each endpoint requires exactly one scope.

### v1 scopes (real)

| Scope             | Grants                                     |
| ----------------- | ------------------------------------------ |
| `identity:read`   | `GET /api/v1/partner/me`                   |
| `webhooks:manage` | All `/api/v1/partner/webhooks/*` endpoints |

The `identity:read` scope is granted automatically to every key — it cannot be revoked while the key is active. This is the minimum scope required to verify an integration is wired correctly.

### Reserved scopes

The following scopes are reserved for future API versions and are **rejected at key-creation time** with a `422` response. They will become real when the corresponding endpoints ship:

* `leads:read`, `leads:write`
* `intakes:read`, `intakes:write`
* `records:read`, `records:write`
* `skills:read`, `skills:author`, `skills:execute`
* `agents:invoke`, `tenants:provision`

If you need an endpoint backed by one of these scopes, reach out before integrating — we can prioritize against real partner demand.

## Verifying your key

The `GET /api/v1/partner/me` endpoint is the canonical integration health check. It works as long as your key is valid and active, and it does not require any specific scope beyond `identity:read`:

```bash theme={null}
curl https://app.vantageclaw.ai/api/v1/partner/me \
  -H "Authorization: Bearer vck_test_REPLACE_ME.your_secret_half_here"
```

Successful response:

```json theme={null}
{
  "partner_org": "your-org-slug",
  "key_id": "vck_test_REPLACE_ME",
  "scopes": ["identity:read", "webhooks:manage"],
  "rate_limit_per_minute": 600
}
```

## Rate limiting

Every key carries a per-minute rate limit, returned by `GET /me` under `rate_limit_per_minute`. Default is 600 requests/minute, keyed by organization. Sustained overage returns `429 Too Many Requests`.

If you need a higher ceiling for a legitimate use case (bulk backfill, high-volume webhook test runs), contact us before designing around the default.

## Key rotation

v1 ships a delete-and-recreate rotation model. There is no in-place rotation endpoint:

1. Request a new key from your VantageClaw contact, granted the same scopes as the old one.
2. Update your integration to use the new key. Test against `GET /me`.
3. Once the new key is in use, request revocation of the old key. The old key returns `401 Unauthorized` immediately after revocation.

For zero-downtime rotation, run both keys in parallel briefly — your application picks up the new key, you confirm traffic flows, then the old key is revoked. The platform tolerates both keys being active during the cutover window.

## Lost or compromised secret

If you suspect the secret half has been exposed:

1. **Immediately** notify your VantageClaw contact so the key can be revoked.
2. Provision a replacement key.
3. Audit your logs for any traffic on the compromised key before revocation.

A revoked key is revoked permanently — the same `vck_<key_id>` will never be re-issued. Any webhook deliveries already in flight at revocation time continue to be signed with their existing HMAC secret (webhook secrets are independent from the API key — see [Webhook security](/webhooks/security)).