API Conventions

Servers

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: https://auth.alianza.com/oauth/token
• Scopes:
  • experience-assignability:check — Permission to invoke the Experience Assignability endpoint to check if a target can be assigned to an Experience

Flow: authorizationCode

• Authorization URL: https://auth.alianza.com/authorize
• Token URL: https://auth.alianza.com/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

Spec gap. The OpenAPI spec does not describe how to obtain or use OAuth2 credentials, so this section relies on out-of-band documentation. See the Authentication guide for the canonical credential lifecycle, then verify the token URL against your environment before integrating.

Gap ID fd67b32ad958

Pagination

The Alianza Enterprise API Design Standard lets each API choose 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 Orchestration 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.

Spec gap. Cursor tokens are typed only as string — format, lifetime, and the error returned for an expired or malformed cursor are unspecified. Treat cursors as opaque, pass them back verbatim, and do not persist them between sessions.

Gap ID cursor-token-semantics

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.

Spec gap. The Alianza Enterprise API Design Standard lists Trace-Id under required HTTP headers, and the spec neither declares it as a request parameter nor returns it as a response header. Whether this API accepts a caller-supplied Trace-Id — and whether it would then reuse that value — is undocumented, so don't rely on supplying your own. Read the returned traceId instead.

Gap ID trace-id-request-header

Error format

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

Rate limits

The Enterprise 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.

Spec gap. The limit above is confirmed by the platform team but is absent from the OpenAPI spec, which declares no 429 response on any operation and no Retry-After or rate-limit headers. Treat a 429 as possible on every endpoint even though it isn't documented, and don't depend on response headers to tell you your remaining budget. Confirm the limits that apply to your credential with your Alianza contact before a high-volume rollout.

Gap ID rate-limit-429