REST API Keys

REST API keys are long-lived credentials (prefix rk_) for calling the Zeotap REST API (/api/v1) from servers, CI/CD pipelines, and automated workflows — anywhere an interactive login isn’t practical.

A REST API key:

• acts as the user who created it, but is capped to the scopes chosen at creation. Its effective access is the intersection of the creator’s current permissions and the key’s scopes, re-evaluated on every request.
• is bound to a single workspace and is rejected on any other workspace.
• can be long-lived (no expiry) or given an optional expiry date, and can be revoked at any time.

Creating a key

Create and manage REST API keys in the Zeotap UI:

1. Navigate to REST API Keys in the left sidebar (under Governance).
2. Click Create REST API Key.
3. Give the key a descriptive Name (e.g. “Customer ETL job”).
4. Select the Scopes — the permissions the key may use. You can only grant permissions you hold yourself, so a key can never widen your access, only narrow it.
5. Optionally set an Expiry Date. Leave it blank for a long-lived key.
6. Click Create Key and copy the key value. It is shown only once and cannot be retrieved later.

Using a key

Send the key as a Bearer token on the Authorization header, along with the X-Workspace-ID header for the key’s workspace:

curl -X GET https://composable.zeotap.com/api/v1/workspaces/{id}/sources \
  -H "Authorization: Bearer rk_abc123..." \
  -H "X-Workspace-ID: 550e8400-e29b-41d4-a716-446655440000"

If a request targets a workspace other than the key’s, or uses a permission outside the key’s scopes, it is rejected:

{
  "error": "api key not valid for this workspace"
}

{
  "error": "permission denied"
}

Scopes

A key’s scopes are permission keys of the form resource.action (for example sources.read, audiences.write, syncs.trigger). The scope picker in the UI lists exactly the permissions you currently hold, grouped by resource.

Because effective access is the intersection of your live permissions and the key’s scopes:

• Selecting fewer scopes produces a more restricted key — the recommended practice for shared or automated integrations.
• If your own permissions are later reduced, the key’s reach shrinks with them automatically.

Revoking a key

Revoke a key from the REST API Keys page. Revocation takes effect immediately — any request using the key afterwards receives a 401 Unauthorized. This cannot be undone; issue a new key to restore access.

Best Practices

• One key per integration — so you can revoke a single integration’s access without affecting others.
• Grant the minimum scopes — a leaked key can then do only what that integration needs.
• Set an expiry for short-lived automation — and rotate long-lived keys periodically.
• Store keys securely — use environment variables or a secrets manager; never commit a key to version control.