Skip to main content

Documentation Index

Fetch the complete documentation index at: https://vantagesolutions.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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)

ScopeGrants
identity:readGET /api/v1/partner/me
webhooks:manageAll /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).