Platform API

The Platform API creates and manages the WorkOS resources that platforms provision on behalf of their users: teams, environments, environment API keys, and team invitations. See the AuthKit for Platforms guide for how these fit together.

All Platform API endpoints are under https://api.workos.com/platform.

Platform endpoints take a bearer token obtained through the OAuth 2.0 client credentials grant, using the credentials WorkOS issues to your platform.

curl --request POST \
  --url "https://signin.workos.com/oauth2/token" \
  -d "client_id=$PLATFORM_CLIENT_ID" \
  -d "client_secret=$PLATFORM_CLIENT_SECRET" \
  -d "grant_type=client_credentials"

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InNzb19vaWRjX2tleV9wYWlyXzAxSlBaWlk3UVA3MTJKMUsyMkI0WlpIMUIzIn0...",
  "expires_in": 3600,
  "token_type": "bearer"
}

Tokens last one hour. Requesting a new token doesn’t invalidate existing ones, so a rolling refresh needs no coordination between workers.

The token must carry the platform scope, which WorkOS attaches to platform credentials. Requests with a token lacking that scope are rejected with 401.

Send the token as a bearer credential on every Platform API request:

--header "Authorization: Bearer $PLATFORM_ACCESS_TOKEN"

Platform API errors return a code to branch on and a message written for people reading logs. Messages can change; codes don’t.

{
  "code": "production_environment_requires_billing",
  "message": "Production environments require active billing. Please set up billing for this team first."
}

A 404 from any endpoint means the resource doesn’t exist or the platform’s access to it has been revoked. Both are terminal, so surface them rather than retrying.