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"
}