Authentication

API keys

Create keys on Configuration → API Access. A key’s scope uses the same permissions as roles: Full access, Read only, or a custom set such as orders:ListOrders and orders:CreateOrder. Keys can have an expiry date and their own rate limit.

Authorization: Bearer wxs_pk_…

Revoking a key takes effect immediately. You can change a key’s scope later, but you can’t view the key again after it is created. If you lose it, revoke it and create a new one.

OAuth 2.1 client credentials

Use this when a service should use short-lived tokens instead of a long-lived key. Register an OAuth client on API Access (a confidential web client gets a secret; scopes are permission names), then exchange its credentials for an access token:

curl -X POST https://v3.revolutionstreetwxs.io/api/auth/oauth2/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d scope="orders:ListOrders orders:CreateOrder"

Send the returned access_token as the bearer token. The discovery document is at https://v3.revolutionstreetwxs.io/.well-known/oauth-authorization-server/api/auth.

Workload identity federation

Lets a workload authenticate without a stored secret. The workload sends a JWT from its own identity provider (GitHub Actions, a cloud workload identity pool, Okta, Entra ID) and gets back a short-lived wxs_ft_… token. The token has the permissions an administrator assigned to that provider under API Access → Identity providers.

curl -X POST https://v3.revolutionstreetwxs.io/api/v3/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "subject_token": "<JWT from your identity provider>",
    "scope": "orders:ListOrders"
  }'

The JWT’s issuer and audience select the provider. Its signature is checked against the provider’s JWKS, and its subject and claims must match the provider’s rules. Request a new token when it expires.

Signed-in sessions

A few screens inside Revolution St, such as the Export page’s downloads and GraphiQL at /api/graphql, call the API with your browser session instead of a key. This only works from Revolution St itself. Integrations must use one of the credentials above.