Developer Preview

Quickstart

Make the first admitted API calls.

Start with health, authentication discovery, tenant-context minting, and read-oriented API calls. Access is admitted during alpha. Credentials and tenant selection instructions are issued privately after approval and smoke proof.

Current Contract

Base URL https://api.afr-dev.axiom.express
API family /v1
Version 0.1.2
Reference /api/reference/0.1.2/

1. Check The API

Health is public and gives a simple connectivity check.

curl -fsS https://api.afr-dev.axiom.express/v1/health \
  -H "X-Correlation-ID: dev-preview-check"

2. Confirm Your Access Pack

Request developer-preview access through help@axiom.express. During alpha, access is approved before credentials are issued. Before writing application code, confirm that the issued access pack contains each value below. Keep these values on your backend.

Browser applications must not hold confidential Axiom credentials, bearer tokens, or tenant-context tokens. Route credential exchange, token refresh, and tenant-context handling through your backend.

Access item How the application uses it
<issued realm> Builds the OpenID discovery URL and identifies the admitted auth realm.
<issued client id> Identifies the admitted client at the token endpoint.
<issued grant type> Controls which token request fields are required.
<issued credential> Used only when the issued grant requires confidential client authentication.
<issued scopes> Requests the admitted API permissions, if scopes are supplied.
<tenant selection payload> Mints the server-owned tenant context after bearer authentication.
<token lifetime guidance> Defines when the backend should refresh or request a new bearer token.

3. Authenticate

Use the issued realm, client, grant type, credential, and scopes. Do not infer tenant authority from client-supplied IDs. Include optional token request fields only when the access pack requires them. 

export AXIOM_AUTH_REALM="<issued realm>"
export AXIOM_CLIENT_ID="<issued-client-id>"
export AXIOM_CLIENT_SECRET="<issued-client-secret-if-required>"
export AXIOM_GRANT_TYPE="<issued grant type>"
export AXIOM_SCOPES="<issued scopes if required>"

curl -fsS "https://auth.afr-dev.axiom.express/realms/${AXIOM_AUTH_REALM}/.well-known/openid-configuration"

curl -fsS -X POST "<token endpoint from discovery>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=${AXIOM_GRANT_TYPE}" \
  --data-urlencode "client_id=${AXIOM_CLIENT_ID}"

# Add only when required by the issued access pack:
#   --data-urlencode "client_secret=${AXIOM_CLIENT_SECRET}"
#   --data-urlencode "scope=${AXIOM_SCOPES}"

The token endpoint, grant requirements, token lifetime, refresh posture, and whether a client secret is used are part of the issued alpha access pack.

4. Mint Tenant Context

Tenant-scoped requests require a server-minted tenant context. Send the returned context token as X-Tenant-Context with the bearer token from the issued auth flow. 

curl -fsS https://api.afr-dev.axiom.express/v1/me/tenants \
  -H "Authorization: Bearer <jwt>" \
  -H "X-Correlation-ID: tenant-discovery"

curl -fsS -X POST https://api.afr-dev.axiom.express/v1/me/tenant-context \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-ID: tenant-context" \
  -d '<tenant selection payload from issued alpha instructions>'
Tenant-context rule Developer handling
Server-minted The API issues tenant context after bearer authentication and admitted tenant discovery.
Tenant-specific Mint a context for the selected tenant and request a new one when the user switches tenants.
Short-lived Cache only on the backend and request a fresh context when the issued one expires.
Bearer-like Treat tenant context as secret request material. Do not place it in public browser storage.
Traceable Send X-Correlation-ID on each call so support can trace failures.

5. Make Read-Oriented Calls

Start with operations visible in the generated OpenAPI reference. Keep early clients read-oriented until the relevant product grammar, role authority, and workflow controls are approved. 

curl -fsS "https://api.afr-dev.axiom.express/v1/parties" \
  -H "Authorization: Bearer <jwt>" \
  -H "X-Tenant-Context: <server-minted tenant context>" \
  -H "X-Correlation-ID: parties-list"

For a complete application path, continue to the policy lookup recipe.