POST /oauth/token
Request an access token for an authenticated user
POST https://coil.com/oauth/token
Request headers
The access token request requires a basic authorization header constructed by base64-encoding the client_id
and client_secret
together.
Use btoa or an equivalent method to generate the header. Pass in the client_id
and client_secret
separated by a colon and URL-encode any reserved characters.
info
URL-encoding usually means that any + signs in the secret should be encoded as %2B.
Name | Value |
---|---|
Content-Type | application/x-www-form-urlencoded |
Authorization | Basic client_id:client_secret_base64 |
Example base64-encoding of client_id:client_secret
// Format
const encodedAuth =
btoa("client_id:" + encodeURIComponent(client_secret))
// Example
const encodedAuth =
btoa("314a...f9fb2:uVE2t7y2y...F4NDloXh5")
Request body
Parameter | Type | Description |
---|---|---|
code | string | The access code assigned by our OIDC provider in the /oauth/auth response. |
grant_type | string | The value must be authorization_code . |
redirect_uri | string | The redirect URI previously registered with our OIDC provider. |
Example request
curl -X POST https://coil.com/oauth/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Basic MzE0YWMxMzQt...ZmMzYy00ZDI4U=' \
-d 'code=CU6LG36vKvVmUbF9QWFwj7F5zvY' \
-d '&grant_type=authorization_code' \
-d '&redirect_uri=https://example.com'
Response parameters
Parameter | Type | Description |
---|---|---|
access_token | string | A JSON web token that your app must use to gain access to the Coil user's resources detailed within the payload of the token. |
expires_in | number | The amount of time in seconds before the access_token expires. The default is 3600 (one hour). |
id_token | string | A JSON web token containing identifying information about our OIDC provider and the session used to acquire the access token. |
refresh_token | string | A JSON web token that your app can use to acquire a new access_token for the Coil user. The refresh token expires in 100 years so it effectively does not expire. The refresh_token should be stored by your app. It's the primary method of obtaining a new access_token when the current one expires. |
scope | string | The scope of user data accessible by the access token: simple_wm and openid . |
token_type | string | Indicates the type of authentication method the access token is to be used with. Our OIDC provider is configured to use the Bearer method. |
Example response
{
"access_token": "eyJhbGciOi...JSUzI1NfsQ",
"expires_in": 3600,
"id_token": "eyJhbGciOiJSUz...I1NiIsInR5",
"refresh_token": "dzfKQUEFYXEZ2~WKq5t0atT36X~",
"scope": "simple_wm", "openid",
"token_type": "Bearer"
}
Next: Call GET /user/info
and use the access_token
to get the authenticated Coil user's resources.
Refresh an expired access token
To refresh an expired access token you must have a refresh token. The refresh token should be stored by your app. It's the primary method for obtaining a new access token when the current one expires.
POST https://coil.com/oauth/token
Request headers
Name | Value |
---|---|
Content-Type | application/x-www-form-urlencoded |
Authorization | Basic client_id:client_secret_base64 |
Request body
Parameter | Type | Description |
---|---|---|
refresh_token | string | The refresh token provided in the response when requesting an access token. |
grant_type | string | The value must be refresh_token . |
scope | string | The scope of user data accessible by the access token: simple_wm and openid . |
Example request
curl -X POST https://coil.com/oauth/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Basic MzE0YWMxMzQt...ZmMzYy00ZDI4U=' \
-d 'refresh_token=dzfKQUEFYXEZ2~WKq5t0atT36X~' \
-d '&grant_type=refresh_token' \
-d '&scope=simple_wm openid'
Response parameters
The response parameters are the same as what's returned when requesting a new access token. The only difference is that a new refresh_token
is provided.
{
"access_token": "eyJhbGciOi...JSUzI1NfsQ",
"expires_in": 3600,
"id_token": "eyJhbGciOiJSUz...I1NiIsInR5",
"refresh_token": "eagLRVFGXYFA3~KDq5t0atT47X~",
"scope": "simple_wm",
"token_type": "Bearer"
}
Revoke an access token
POST https://coil.com/oauth/token/revocation
Request headers
Name | Value |
---|---|
Content-Type | application/x-www-form-urlencoded |
Authorization | Basic base64(client_id:client_secret) |
Response body
Parameter | Type | Description |
---|---|---|
token | string | The refresh token associated with the user to revoke access from. |
Example request
curl -X POST https://coil.com/oauth/token/revocation \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Basic MzE0YWMxMzQt...ZmMzYy00ZDI4U=' \
-d 'token=CU6LG36vKvVmUbF9QWFwj7F5zvY' \