OAuth Tokens API

HTTP Requests for handling Access Token, ID Token, and Refresh Tokens

Getting Tokens using Identity Token

After successfully verifying user's email or phone number, you'll receive Cotter's Identity Token. Pass it to the body of the request under field identity_token

curl -XPOST \
-H 'API_KEY_ID: <YOUR API KEY ID>' \
-H 'API_SECRET_KEY: <YOUR API SECRET KEY>' \
-H "Content-type: application/json" \
-d '{
"grant_type": "identity_token",
"identity_token": { // ๐Ÿ‘ˆ Put Identity Token Here
"expire_at": "1588849208",
"identifier": "[email protected]",
"identifier_id": "e8a47aff-f520-4b8d-952b-79d36d10fb3e",
"identifier_type": "EMAIL",
"receiver": "<YOUR API KEY ID>",
"signature": "21P6mXSF2x357kZGkEMQTRTn3r...",
"timestamp": "1586257208"
}
}' 'https://www.cotter.app/api/v0/token'

post
Getting Tokens using Identity Token

https://www.cotter.app/api/v0/token
Getting OAuth tokens using Cotter's Identity Token
Request
Response
Request
Headers
API_KEY_ID
required
string
Your API_KEY_ID
API_SECRET_KEY
required
string
Your API_SECRET_KEY
Content-type
optional
string
application/json
Body Parameters
grant_type
required
string
Grant type is identity_token
identity_token
required
object
Cotter's Identity Token returned to you after successfully verifying user's email or phone number.
Response
200: OK
Receive the access_token, id_token and refresh_token
{
"access_token": "eyJhbGciOiJFUzI1Ni...",
"auth_method": "OTP",
"expires_in": 3600,
"id_token": "eyJhbGciOiJFUzI1N...",
"refresh_token": "17:nQEk14mCp4sQs5...",
"token_type": "Bearer"
}

Getting Tokens using Event Token

After successfully authenticating users using Trusted Devices, you will receive Cotter's Event Token. Pass it to the body of the request under field event_token

curl -XPOST \
-H 'API_KEY_ID: <YOUR API KEY ID>' \
-H 'API_SECRET_KEY: <YOUR API SECRET KEY>' \
-H "Content-type: application/json" \
-d '{
"grant_type": "event_token",
"event_token": { // ๐Ÿ‘ˆ Put Event Token Here
"CreatedAt": "2020-04-07T11:09:03.246703978Z",
"DeletedAt": null,
"ID": 264,
"UpdatedAt": "2020-04-07T11:09:03.246703978Z",
"approved": true,
"client_user_id": "xyzABC123",
"event": "LOGIN",
"ip": "73.15.208.6",
"issuer": "<YOUR API KEY ID>",
"location": "San Francisco",
"method": "TRUSTED_DEVICE",
"new": false,
"signature": "CLQUgAUEuMebLAEQ...",
"timestamp": "1586257743"
}
}' 'https://www.cotter.app/api/v0/token'

post
Getting Tokens using Event Token

https://www.cotter.app/api/v0/token
Getting OAuth tokens using Cotter's Event Token
Request
Response
Request
Headers
API_KEY_ID
required
string
Your API_KEY_ID
API_SECRET_KEY
required
string
Your API_SECRET_KEY
Content-type
optional
string
application/json
Body Parameters
grant_type
required
string
Grant type is event_token
event_token
required
object
Cotter's Event Token returned to you after successfully authenticate users using Trusted Device
Response
200: OK
Receive the access_token, id_token and refresh_token
{
"access_token": "eyJhbGciOiJF...",
"auth_method": "TRUSTED_DEVICE",
"expires_in": 3600,
"id_token": "eyJhbGciOiJFUzI1...",
"refresh_token": "19:1LWieVqH5LlM1t...",
"token_type": "Bearer"
}

Renewing Tokens using Refresh Token

If Cotter's SDK doesn't support auto renewal, or if you you need to renew the tokens manually, you can make an HTTP request to Cotter's Server to renew the tokens using a refresh_token.

curl -XPOST \
-H 'API_KEY_ID: <YOUR API KEY ID>' \
-H 'API_SECRET_KEY: <YOUR API SECRET KEY>' \
-H "Content-type: application/json" \
-d '{
"grant_type": "refresh_token",
"refresh_token": "<REFRESH_TOKEN>"
}' 'https://www.cotter.app/api/v0/token'

post
Get Token using Refresh Token

https://www.cotter.app/api/v0/token
Getting new access_token and id_token using refresh_token
Request
Response
Request
Headers
Content-type
optional
string
application/json
API_KEY_ID
required
string
Your API_KEY_ID
API_SECRET_KEY
required
string
Your API_SECRET_KEY
Body Parameters
grant_type
required
string
Grant type is refresh_token
refresh_token
required
string
Your refresh_token
Response
200: OK
Returns a new access_token and id_token. Does not return a new refresh_token
{
"access_token": "eyJhbGciOiJFU...",
"auth_method": "OTP",
"expires_in": 3600, // expiry in seconds
"id_token": "eyJhbGciOiJFUzI1N...",
"token_type": "Bearer"
}

Note that this does not return a new refresh_token