Client Credentials Flow

The Client Credentials Flow is used for external clients to fetch an access token to use with the Switch API.

The Client Credentials Flow (as defined in OAuth 2.0 RFC 6749) involves an application exchanging its application credentials, such as and , for an access token.

This flow is best suited for Machine-to-Machine (M2M) applications, such as CLIs, daemons, or backend services, because the system must authenticate and authorize the application instead of a user.

How it works

1. Client application sends application's credentials to the Authorization Server.

2. The Authorization Server validates application's credentials.

3. The Authorization Server responds with an access token.

4. The client application can use the access token to call the API on behalf of itself.

5. The API responds with requested data.

Parameters

Following are the request parameters needed when making the fetch access token call to the authorization server.

Parameter Name	Description
grant_type (required)	Must be set to client_credentials.
client_id (required)	The client application ID.
client_secret (required)	The client application secret.
audience (required)	The audience for the token, which is in fact the Switch API.

Request

The following is an example authorization code grant request the Authorization Server would receive.

cURL

curl --request POST \
  --url 'https://{authorization-server.com}/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=YOUR_CLIENT_ID \
  --data client_secret=YOUR_CLIENT_SECRET \
  --data audience=API_AUDIENCE

C#

var client = new RestClient("https://{authorization-server.com}/oauth/token");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/x-www-form-urlencoded");
request.AddParameter("application/x-www-form-urlencoded", "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&audience=API_AUDIENCE", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Java

HttpResponse<String> response = Unirest.post("https://{authorization-server.com}/oauth/token")
  .header("content-type", "application/x-www-form-urlencoded")
  .body("grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&audience=API_AUDIENCE")
  .asString();

NodeJS

var axios = require("axios").default;

var options = {
  method: 'POST',
  url: 'https://{authorization-server.com}/oauth/token',
  headers: {'content-type': 'application/x-www-form-urlencoded'},
  data: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    audience: 'API_AUDIENCE'
  })
};

axios.request(options).then(function (response) {
  console.log(response.data);
}).catch(function (error) {
  console.error(error);
});

Response

If all goes well, you'll receive an HTTP 200 response with a payload containing access_token, token_type, and expires_in values:

{
  "access_token":"eyJz93a...k4laUWw",
  "token_type":"Bearer",
  "expires_in":86400
}

The returned access token from the Switchmarket Authorization Server will be valid for 1 hour only. After that you need to generate new one in order to be able to access the Switchmarket API.

The Client Credentials flow is used by the platform organization clients whose secrets can be managed by the organization administrators.