Authentication

All Alianza Experience API calls require an OAuth 2.0 access token sent as Authorization: Bearer <token>. There are two grant types and one optional discovery mechanism.

Authentication uses a dedicated auth base URL ({baseAuthUrl}), separate from the API base URL.

Base URLs

The authentication base URL is fixed per environment, regardless of the end user's phone number or account:

Environment Referenced as URL
Production API {baseUrl} https://api.alianza.com
Sandbox API {baseUrl} https://api.b2.alianza.com
Production Auth {baseAuthUrl} https://auth.alianza.com
Sandbox Auth {baseAuthUrl} https://auth.beta.alianza.com

Which grant to use

Grant When Pages
Client Credentials Server-to-server calls with no end-user context. Use this for the eligibility check before signup. Always act as an OAuth2 confidential client with this grant. Client Credentials
Authorization Code + PKCE Acting on behalf of an authenticated user (e.g. creating a connection on their account). Authorization Code + PKCE
Home Realm Discovery Optional. Skip the IdP picker by hinting which identity provider to use. Home Realm Discovery

Token endpoints

Endpoint Used by
POST {baseAuthUrl}/oauth/token Client Credentials and Authorization Code grants
GET {baseAuthUrl}/authorize Authorization Code + PKCE only

Scopes

Scopes are declared in the OpenAPI spec's oauth2 security schemes. The scopes relevant to Experience integrations:

Scope Grants permission to
experience-assignability:check Invoke the Experience Assignability endpoint
experience-connections:manage List, retrieve, create, update, and delete Experience Connections for your Experience
experience-assignments:manage List, retrieve, create, and delete Experience Assignments for your Experience

The spec also declares tenant- and account-scoped management scopes (tenant-experience-authorizations:manage, tenant-experiences-catalogs:manage, tenant-experiences-profiles:manage, account-experiences-authorizations:manage, principals:manage) used by Service Provider integrations, not Experience Providers.

Token caching and refresh tokens

Access tokens are valid for the duration in expires_in (seconds). Cache them until shortly before they expire rather than requesting a new token per call.

To obtain a refresh token, include the offline_access scope on the /authorize request. The subsequent /oauth/token request then returns a refresh token alongside the access token, letting your Experience get new access tokens without sending the user through sign-in again.

Retrieving a new access token

POST {baseAuthUrl}/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token={refresh_token}

Token lifetimes

Setting Value
Access token lifetime 15 minutes
Refresh token rotation Enabled
Refresh token maximum lifetime 180 days
Refresh token idle timeout 90 days

Rotation is enabled, so each refresh returns a new refresh token and invalidates the one you used. Persist the new value on every refresh — reusing a spent refresh token fails. Two clocks then run against you: a refresh token dies 90 days after it was last used, and the chain cannot be extended past 180 days from the original grant regardless of activity. Plan for the user to re-authenticate at least every 180 days.

Client secret rotation

Alianza rotates client secrets through a pre-staged process, so there is no window in which neither secret works:

  1. Alianza generates a new client secret.
  2. The new secret is sent to you over an agreed out-of-band channel.
  3. You deploy it as a secondary or fallback credential, while still using the current secret.
  4. Alianza activates the new secret on the client configuration.
  5. You remove the previous secret from your environment.

Your existing secret stays valid until step 4, and the staged secret becomes active immediately at step 4 — which is why step 3 must be complete before then. Build your credential store to hold two secrets at once and to accept either on retry.

See also