Authentication

🔑

You need an Experiture account to use this API

If you have platform access, sign in to portal.experiture.com and create an OAuth client under My Organization → API Access. If you're a developer without full platform access, ask your Experiture Account Administrator for OAuth credentials, or email support@experiture.com.

The Experiture Public API authenticates requests with bearer tokens. Every endpoint under https://api.experiture.ai/public/v1 requires a valid token in the Authorization header.

Token Format

Authorization: Bearer <your_access_token>

Tokens are JWT RS256 Bearer tokens obtained via the OAuth 2.0 client credentials grant. They are issued per workspace and carry the scopes granted to the OAuth client used to obtain them.

Tokens are secrets — treat them like passwords. Never commit them to source control or ship them in client-side bundles.

Creating an OAuth Client

There are two ways to obtain an OAuth client, depending on your access level.

If you have platform access:

Sign in to the Experiture console at portal.experiture.com (opens in a new tab).
Navigate to My Organization → API Access.
Click New Client, name it (e.g. etl-pipeline-prod), and choose scopes.
Copy the Client ID and Client Secret — the secret is shown once. Store both in your secrets manager immediately.
Exchange the client credentials for a Bearer token using the OAuth 2.0 client credentials grant. Your token endpoint and full instructions are shown in the console after client creation.

If you're a developer without platform access:

Ask your Experiture Account Administrator to provision an OAuth client and share the Client ID, Client Secret, scopes, and token endpoint with you through a secure channel. If you don't know who your administrator is, email support@experiture.com and the Experiture team will route your request.

Grant the minimum scopes needed. One client per service makes revocation clean — if a service is compromised, you rotate only that client.

Scopes

All scopes use the cdp: prefix.

Scope	Permits
`cdp:records:write`	All append/upsert endpoints on `/records/*`.
`cdp:records:read`	Job status polling and metadata lookups for records.
`cdp:contacts:write`	Write contact records.
`cdp:contacts:read`	Read contact records and profile data.
`cdp:profiles:write`	`POST /profiles/upsert`.
`cdp:profiles:read`	Read profile records and metadata.
`cdp:lists:write`	Create, update, delete lists and members.
`cdp:lists:read`	List and read list metadata.
`cdp:segments:write`	Create and update segments.
`cdp:segments:read`	Read segment definitions (required for audiences and lists).
`cdp:imports:write`	Create and start import jobs.
`cdp:imports:read`	Poll import job status and download error files.
`cdp:audiences:preview`	`POST /audiences/{id}/preview`.
`cdp:metadata:read`	`GET /metadata/objects/*`.

Campaigns API scopes use a separate campaigns: prefix and cover the full campaign lifecycle.

Scope	Permits
`campaigns:read`	List campaigns, get campaign detail, summary, status; run preflight.
`campaigns:create`	Create new campaigns and clone existing ones.
`campaigns:update`	Update metadata, audience binding, content binding, schedule intent.
`campaigns:delete`	Soft-delete and archive campaigns.
`campaigns:schedule`	Schedule a campaign send via `POST /campaigns/:id/schedule-jobs`.
`campaigns:send`	Trigger an immediate send via `POST /campaigns/:id/send-jobs`.
`analytics:read`	Read execution pipeline metrics via `GET /campaigns/:id/metrics`.

Grant the minimum scopes needed for each client. Full workspace access is not recommended for production services.

Request Example

curl https://api.experiture.ai/public/v1/metadata/objects \
  -H "Authorization: Bearer <your_access_token>"

If the header is missing or the token is invalid, the API returns 401 Unauthorized:

{
  "success": false,
  "correlationId": "<uuid>",
  "error": {
    "code": "CDP_ETL.AUTH.UNAUTHORIZED",
    "message": "Missing or invalid bearer token.",
    "details": {},
    "remediation": "Obtain a valid access token via the OAuth 2.0 client credentials grant."
  }
}

If the token is valid but lacks the required scope, you get 403 Forbidden:

{
  "success": false,
  "correlationId": "<uuid>",
  "error": {
    "code": "CDP_ETL.AUTH.FORBIDDEN",
    "message": "Token missing required scope: cdp:records:write",
    "details": {},
    "remediation": "Re-issue an access token from an OAuth client that has the required scope."
  }
}

Rotation & Revocation

Rotate client secrets regularly as a best practice. Create a new token with the updated secret, deploy it, then revoke the old one.
Revoke immediately if a client secret may have leaked. Use the console under My Organization → API Access to delete or disable the client.
Tokens issued from a revoked client will be rejected on subsequent validation.

Best Practices

Store in a secrets manager — AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, Doppler, etc. Never hard-code.
One client per service — if a service is compromised, you only rotate one client. Use naming like etl-pipeline-prod, website-signup-form, mobile-app-server.
Least privilege — grant the minimum scopes. A webhook sink only needs cdp:records:write.
Never send tokens to browsers. Client-side code should call your backend, which calls Experiture with the token server-side.
Log correlation IDs, not tokens — every response includes a x-correlation-id header for debugging.