Skip to main content
POST
Exchange an API key for an access token

Authorizations

Authorization
string
header
required

A machine-client token from POST /v1/auth/client-token. Reads need the pulse.read scope; provisioning and tenant updates need pulse.write, which the token only carries when requested_scopes asks for it. Creating, changing, disabling and resetting MFA for users, and the tenant sign-in policy, need a signed-in user's token instead: they reject API-key tokens.

Body

application/json

Exchanges an API key (client id and secret) for a bearer token for the key's own tenant.

client_id
null | string
required

The API key's client id, which starts with pc_.

client_secret
null | string
required

The API key's secret, which starts with pcs_. It is shown only once, when the key is created.

requested_scopes
null | string[]
required

The scopes the token should carry: pulse.read, pulse.write, or both.

When omitted, the token gets pulse.read only, even if the key also holds pulse.write. Provisioning, suspend, reactivate, decommission, job status, updates and user management all need pulse.write, so ask for it explicitly. Asking for a scope the key does not hold returns 403 scope_denied.

Response

OK

A bearer token. Send it as Authorization: Bearer <access_token>. There is no refresh token: request a new one before expires_at.

access_token
string
required

The bearer token (a signed JWT).

token_type
string
required

Always Bearer.

expires_in
required

Seconds until the token expires: 3600 (one hour) by default.

expires_at
string<date-time>
required

When the token expires: an ISO 8601 timestamp in UTC (offset +00:00).

subject_type
string
required

Always machine_client.