Skip to content

Client Credentials Grant

The OAuth 2.0 client credentials grant allows a confidential client to exchange their client credentials for a client token.

Scopes

Client token scopes are all prefixed with client:.

Available Scopes

Scope Description
client:send Send messages to users.
client:connections View connections between the client and users.
client:outbound_messages View outbound messages sent by the client.

Token Request

POST https://projectalias.com/api/oauth2/token

See the OAuth 2.0 spec for more details on the token endpoint.

Authentication

The client must authenticate themselves with HTTP basic auth, using their client credentials. The client ID is used as the user-id, and the client secret as the password.

Warning

This request should only be performed from a secured backend as it requires sensitive client credentials.

Request Body

The request body must be encoded as application/x-www-form-urlencoded, and the Content-Type header set appropriately.

Field Required Description
grant_type Yes Must be client_credentials
scope Yes A space separated list of client scopes.

Response Body

The response body is encoded as application/json.

Field Type Description
access_token string A client token.
token_type string Always Bearer.
expires_in integer How many seconds the token will be valid for. Tokens are valid for 30 minutes.
scope string A space separated list of scopes the token has.

Errors

In case of an error, the endpoint will endevour to respond with an appropriate HTTP status code. It may include details of the error in an application/json response body.

Field Type Description
error string An error code.
error_description string An optional human-readable description of the error.

See the relevant section of the OAuth 2.0 spec for details of the OAuth 2.0 specific error codes. Note that you may receive error codes not defined in the spec.

Examples

Example Request

POST /api/oauth2/token HTTP/1.1
Host: projectalias.com
Authorization: Basic <basic-credentials>
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=client%3Asend%20client%3Aconnections
curl -XPOST "https://projectalias.com/api/oauth2/token" \
    -H "Authorization: Basic <basic-credentials>" \
    -d "grant_type=client_credentials" \
    -d "scope=client:send client:connections"
import requests
r = requests.post('https://projectalias.com/api/oauth2/token',
                  headers={'Authorization': 'Basic <basic-credentials>'}
                  data={'grant_type': 'client_credentials',
                        'scope': 'client:send client:connections'})

Example Response

{
    "access_token": "x-o7XwWiGWCBkH_TKV-slC8IP_DACpN2k9qQO3q2sV1y4b_fvJgBBIP7xlnmpW1ZZ2JojcpK-SP8G1dFKETn7zBdr8Q_xQsbGQ3upIY45u1AL8vhQLsMWOK8Npv4KlblD_6Ium0jm-16cYBSd8I0l3Xy0qklwsvvNkqYnpX5mUg2eYYVUwafiW7lwApmOAzjQuYME78kRfkqXwu8gqMzmB0IK0jw3by_ZjGbYaadv3HaIzzmjs1HsAvTwvoZ4KKF-jdk5i7LevoGXrsHqeSKmM2vx5CJA0E5O_vIy5mHqU-ZxBL1v5EOdBS7QfpUVlMuByCMCq0xoww7Ygz458rLRw0sTK_jD563EfWZefePbFLI9ApTe1ULTxbZxaFNomktUKifrFruk8lyh7i9UykoKLV_Cl_MmOc1AYO_YPrg5irtMC-oHwE5xgyonjdYq4hJcgMoy5R-oUYnAiGnDyTHhMCPJ-Lmzr0kWo6v7S7VIr4mFXpqNN7isQtcMoTFd2MmYfaWyzGuTuk4xBXhilyO0OIo0_XPauD8eIC-LXyNd7l67ENTs_1iXCzOTzf_NKiXLlThXY7aA2XOOnJcQVLBIpjVRRk2aWezOIaakpXkg0HGiUzdBBttCXEZoSF68IftUXJVrmkS_oW3w_4dcIAvUeUb6opCDXcmg09fNwJgIRs",
    "token_type": "Bearer",
    "expires_in": 1800,
    "scope": "client:send client:connections"
}