POST /oauth/token

Request an access token for an authenticated Coil user

Request an access token

POST https://coil.com/oauth/token

Query 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.

URL-encoding usually means that any + signs in the secret should be encoded into %2B

Key

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:client_secret")
// Example
const encodedAuth =
btoa("314a...f9fb2:uVE2t7y2y...F4NDloXh5")

Query parameters

Parameter

Type

Description

code

string

The access code assigned by the 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 the 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 the 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. Also email if authorized.

token_type

string

Indicates the type of authentication method the access token is to be used with. The 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: 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

Query headers

Refreshing an access token requires the same authorization header as used in the access token request.

Key

Value

Content-Type

application/x-www-form-urlencoded

Authorization

Basic client_id:client_secret_base64

Query parameters

Parameter

Type

Description

refresh_token

string

The refresh token provided in the response when requesting an access token.

grant_type

string

Since you're refreshing an access token, the value must be refresh_token.

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

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_tokenis provided.

Example response

{
"access_token": "eyJhbGciOi...JSUzI1NfsQ",
"expires_in": 3600,
"id_token": "eyJhbGciOiJSUz...I1NiIsInR5",
"refresh_token": "eagLRVFGXYFA3~KDq5t0atT47X~",
"scope": "simple_wm",
"token_type": "Bearer"
}