Skip to main content

Auth

Authentication with the xPage API uses short-lived access tokens obtained by exchanging your app's credentials. Every token request requires a valid client_id and client_secret — issued when your app is registered.

Keep your credentials secret

Your client_secret must never be exposed in client-side code, version control, or shared with third parties. Treat it like a password.

Get Token​

Endpoint​

POST /api/apps/v1/auth/get-token

No authentication is required for this endpoint — it is the credential exchange itself.

You can pass credentials either as a JSON body (shown below) or as HTTP Basic Auth with client_id as the username and client_secret as the password.

Request​

{
  "client_id": "public_...",
  "client_secret": "secret_...",
  "install_id": "uuid",
  "ttl": 3600
}
FieldTypeRequiredDescription
client_idstringYesYour app's public client identifier
client_secretstringYesYour app's secret credential
install_iduuidNoScope the token to a single installation (recommended)
ttlintegerNoToken lifetime in seconds. Default: 3600. Max: 86400 (24 h)

Token Types​

Pass an install_id to bind the token to a single hosting installation. The installation scope is embedded in the token itself — no additional headers are needed when making API calls.

{
  "client_id": "public_...",
  "client_secret": "secret_...",
  "install_id": "550e8400-e29b-41d4-a716-446655440000"
}

Full access token​

Omit install_id to obtain a token that can access any installation your app has been granted. Every subsequent API request must include the target installation via the X-App-Install-Id header.

{
  "client_id": "public_...",
  "client_secret": "secret_..."
}
Why restricted tokens are preferred

A restricted token limits the blast radius if a token is ever leaked — it cannot be used against any other installation. Full access tokens require you to manage the X-App-Install-Id header on every request and expose a larger surface area.

Response​

{
  "data": {
    "app": {
      "id": "uuid",
      "client_id": "public_...",
      "created_at": "2024-01-01T00:00:00Z"
    },
    "token": "a3f9c2...",
    "ttl": 3600
  }
}

Store the returned token value — this is the bearer token used in all subsequent API requests.

Using the Token​

Pass the token as a Bearer token in the Authorization header:

curl -H "Authorization: Bearer <token>" \
     https://...

For full access tokens, also include the target installation:

curl -H "Authorization: Bearer <token>" \
     -H "X-App-Install-Id: 550e8400-e29b-41d4-a716-446655440000" \
     https://...

Token Expiry & Renewal​

Tokens expire after their ttl (default 1 hour). Your application must handle renewal proactively — the API will return 401 Unauthorized once a token has expired.

Recommended pattern:

  1. Generate a new token using your credentials before expiry.
  2. Cache the token server-side using the ttl from the response to calculate the expiry time.
  3. Treat the token as a short-lived session credential — regenerate it as needed, never store it long-term.
Cache the token, not just the secret

Requesting a new token on every API call is wasteful. Cache the token server-side and refresh it a few minutes before expiry. Never pass the token to the browser or any client-side context.

CURL Example​

curl -X POST https://.../api/apps/v1/auth/get-token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "public_...",
    "client_secret": "secret_...",
    "install_id": "550e8400-e29b-41d4-a716-446655440000",
    "ttl": 3600
  }'

Or using Basic Auth:

curl -X POST https://.../api/apps/v1/auth/get-token \
  -u "public_...:secret_..." \
  -H "Content-Type: application/json" \
  -d '{ "install_id": "550e8400-e29b-41d4-a716-446655440000" }'

Verify Token (me)​

GET /api/apps/v1/auth/me
Authorization: Bearer <token>

Returns the authenticated app and, if the token is restricted to an installation, its install_id. Useful for verifying credentials and debugging token scope.

Response​

{
  "data": {
    "app": {
      "id": "uuid",
      "client_id": "public_...",
      "created_at": "2024-01-01T00:00:00Z"
    },
    "install_id": "uuid"
  }
}

install_id is only present when the token is a restricted token. For full access tokens, it is omitted.