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' \