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:

POST https://litmus.com/oauth/token

JSON POST body parameters:

Field	Description
client_id	REQUIRED The client ID you received from Litmus
client_secret	REQUIRED The client secret you received from Litmus
grant_type	REQUIRED 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 "https://api.litmus.com/v3/ping/authenticated"\
       -H "Authorization: Bearer c828a87e8d82ca186e59a367dbca9c9541888e06a68"
       -v

> GET /v3/ping/authenticated HTTP/1.1
> Host: api.litmus.com
> 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",
      "expiresInSeconds":6908,
      "scopes" : ["full"]
    },
    "application" : {
      "name" : "v3 client application",
      "uid" : "50cfeefee012c4c16ff750d9ebbada8176b5a6fda6b"
    }
  }
}

Scopes

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.