Authentication & scopes

Every Connect API request requires an Authorization header with a Bearer token:

Authorization: Bearer rocketlead_live_<64-hex-secret>

Anything that doesn’t start with rocketlead_ is rejected with 401 Unauthorized.

Issuing a token

Tokens are managed in the RocketLead console under Settings → API Tokens.

Caution

The secret is shown once. Copy it immediately — it can’t be retrieved later. Store it in your secrets manager / .env. If lost, revoke and re-issue.

You can also set:

• Expiration — optional. Non-expiring tokens are valid until revoked.
• Scopes — required. See below.

Scopes

Three scopes control what a token can do:

Scope	Allowed methods	Use case
read	GET, HEAD, OPTIONS	Read-only sync (export leads, fetch bookings, mirror availability)
write	All read + POST, PATCH, PUT	Create leads from your CRM, book slots, update lead state
admin	All write + DELETE	Full integration including deleting bookings

Scope mismatches return 403 Forbidden. Issue the narrowest scope that satisfies your integration.

Token lifecycle

• lastUsedAt is updated on every authenticated request — you can see when a token was last active in the console.
• Revocation is instant. Once revoked, future requests with that token return 401.
• Rotation — revoke the old token after the new one is in production traffic. There’s no automatic migration window.

Errors

Status	Meaning
400	Validation error (bad input, missing field, invalid combination)
401	Missing, malformed, expired, or revoked token
403	Token scope insufficient for the requested method
404	Resource not found (or not in your organization)
500	Internal — retry with backoff

Errors follow the standard envelope:

{ "statusCode": 400, "message": "Validation failed: tableId is required" }

Related

• Connect API Overview — base URL, link to interactive /docs reference.
• Race conditions & idempotency — retry strategies for 409/429/transient failures.