API Conventions

Servers

Authentication uses a separate base URL. See Authentication for both values.

Authentication

All operations require an OAuth 2.0 bearer token in the Authorization: Bearer <token> header. Two grant types are used; the Authentication guide covers each in detail. The OpenAPI spec declares the following flows:

oauth2

Type: oauth2

Flow: clientCredentials

• Token URL: {baseAuthUrl}/oauth/token
• Scopes:
  • experience-assignability:check — Permission to invoke the Experience Assignability endpoint to check if a target can be assigned to an Experience
  • users:manage — Permission to list and retrieve unified users for accounts connected to your Experience

Flow: authorizationCode

• Authorization URL: {baseAuthUrl}/authorize
• Token URL: {baseAuthUrl}/oauth/token
• Scopes:
  • experience-assignments:manage — Permission to list, retrieve, create, and delete Experience Assignments for your Experience
  • experience-connections:manage — Permission to list, retrieve, create, update, and delete Experience Connections for your Experience
  • users:manage — Permission to list and retrieve unified users for accounts connected to your Experience

Pagination

Alianza APIs use one of two pagination styles — offset-based or cursor-based. This API is cursor-paged. Don't carry that assumption to other Alianza APIs: an offset-paged API takes pageNum instead of cursor, and a cursor-paged one does not always expose pageSize. Check the reference for whichever API you are calling.

The Crux API's list endpoints accept two query parameters:

Responses are a paged envelope containing entities, the pageSize applied, and a cursor. Keep requesting with the returned cursor until it comes back null, which signals the last page. There is no total count and no page number — you cannot jump to an arbitrary page.

Changed in 1.0.0: the pageSize maximum dropped from 200 to 100. A request for more than 100 items now fails validation rather than being clamped.

Identifiers

• Resource IDs are UUIDs (RFC 4122).
• Phone numbers are E.164 format (e.g. +14155551234).
• Timestamps are ISO 8601 in UTC (e.g. 2026-03-01T12:00:00Z).

Tracing

Alianza generates a trace ID for every request and returns it to you. You do not need to send one.

Error responses carry it in the traceId field of the ProblemDetails body, where it is a required field — so any failure you can see, you can quote. Log traceId whenever you handle a non-2xx response. It is the fastest way for Alianza to find your specific request, and without it a support conversation starts with narrowing down which call you mean.

Successful responses do not include a trace ID. In practice that is rarely a problem — the calls you need traced are the ones that failed.

Error format

Errors use RFC 9457 application/problem+json with the ProblemDetails shape. See Errors.

Rate limits

The Crux API applies a default limit of 100 requests per second. It is enforced per authorized credential on endpoints that require authorization, and per client IP address on endpoints that don't — so every endpoint in this API is metered against your OAuth2 credential, not your IP.

Individual services may define their own limits that override the default. None currently do, so 100 requests per second is the effective ceiling across this API today.

That is a generous budget for the work this API involves. A full re-sync of 10,000 Experience Connections is 100 requests at the maximum pageSize — about a second of traffic. You are far more likely to hit the limit through a retry storm than through legitimate paging, so cap concurrency and back off on failure rather than engineering around the ceiling.