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:

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:

curl https://app.vantageclaw.ai/api/v1/partner/me \
  -H "Authorization: Bearer vck_test_REPLACE_ME.your_secret_half_here"

Successful response:

{
  "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).