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 client ID and client secret, 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#

Java

NodeJS

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 Switch Authorization Server will be valid for 24 hours only. After that you need to generate new one in order to be able to access the Switch API.

It is important that the fetched access token is cached by the client for the duration of its validity and reused for subsequent requests. The Switch Authorization Server imposes rate limits on the token endpoint which when reached will reject the requests to fetch an access token for a given time period.

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