Skip to content

OAuth Client Credentials Flow

The Client Credentials Flow

1. Request an access token

Your application server should POST using its client_secret to obtain a token:


JSON POST body parameters:


The client ID you received from Litmus

The client secret you received from Litmus

This must be client_credentials

JSON response body

  "access_token": "c828a87e8d82ca186e59a367dbca9c9541888e06a68",
  "expires_in": 7200,     // The remaining lifetime of the token in seconds
  "token_type": "Bearer"  // The token type, currently always Bearer

  // More fields may be provided

You must store the access token to make future requests. But you should treat the access token as a secret, like a password. Never reveal it to your end-users (for example: do not pass the token to user-facing web pages where the user would be able to extract it).

2. Call Litmus API methods passing the token

Make authenticated calls to our APIs from your application server using the HTTP Authorization header:

$ curl ""\
       -H "Authorization: Bearer c828a87e8d82ca186e59a367dbca9c9541888e06a68"

> GET /v3/ping/authenticated HTTP/1.1
> Host:
> User-Agent: curl/8.4.0
> Accept: */*
> Authorization: Bearer c828a87e8d82ca186e59a367dbca9c9541888e06a68
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8
  "meta" : {
    "ping" : "pong",
    "accessToken" : {
      "token" : "c828a87e8d82ca186e59a367dbca9c9541888e06a68",
      "scopes" : ["full"]
    "application" : {
      "name" : "v3 client application",
      "uid" : "50cfeefee012c4c16ff750d9ebbada8176b5a6fda6b"


Currently only one scope, full ("Use all Litmus features") is currently provided (this is also the default when none is specified).

Token expiration and refresh

Token expiry should be anticipated (the default token time-to-live is 2hrs, but this may change).

Refresh tokens are supported and are the recommended approach to obtaining a new bearer token. Restarting the flow above will also issue a fresh token.

Token revocation

Token revocation should also be anticipated and handled gracefully by restarting the flow.