Authentication & Security Reference

These endpoints manage programmatic access and security identities within Keystone CDP integrations.

API Key Management

These endpoints allow workspace administrators to manage scoped keys for integrations and web tracking.

1. Create API Key (POST /tenant/apikeys)

Generates a new restricted API key for external systems.

  • Payload:

json { "name": "Web Tracker Key", "scopes": ["ingest"], "allowed_domains": ["https://mysite.com"] }

  • Security: Returns the raw api_key ONLY ONCE. Subsequent requests will only show metadata.
  • Privacy: The key is stored securely using cryptographic hashes.

2. List API Keys (GET /tenant/apikeys)

Returns metadata for all keys associated with your workspace.

  • Fields: id, name, scopes, allowed_domains, created_at.
  • Privacy: Does NOT return the secret key value itself.

3. Delete API Key (DELETE /tenant/apikeys/{key_id})

Revokes programmatic access for the specified key immediately.

Authorization Patterns

X-API-Key Header

The primary authorization mechanism. The key is validated against the registry and resolves your workspace environment and assigned Scopes.

GET /api/ingest
X-API-Key: YOUR_API_KEY

Backend Dependency Enforcement

Endpoints are secured dynamically, verifying your key scopes against the operation requested. If a key lacks the required scopes, a 403 Forbidden response is returned.

Scopes & Permissions

When generating API keys, they must be assigned specific scopes to restrict what external systems can do.

  • admin: Allows full management of integrations, settings, and data exports.
  • editor: Allows data manipulation (CRUD on customers/products) but blocks system setup.
  • viewer: Restricted to GET requests on reporting endpoints.
  • ingest: Strictly limited to submitting new tracking events. Cannot read data.