Authorization with OAuth 2.0

OAuth 2.0 protocol is used for authentication and authorization. We currently support the OAuth 2.0 protocol grant type called client credentials grant to cover common application-to-application integration scenarios.
The OAuth 2.0 specification is available here.
We require that all requests are using HTTPS over TLS.

Get Access Token

Get an OAuth 2.0 access token for the requesting client. As mentioned above, client_id and client_secret are issued by Cogito.

Endpoint

POST /api-ext/domain/{domain}/token

Header

NameRequiredDescription
content-typerequiredMust be application/x-www-form-urlencoded
authorizationrequiredBasic authorization formed by base64 encoding the issued client_id and client_secret

Path Parameters

NameRequiredTypeDescription
domainrequiredstringClient's unique name

Body Parameters

NameRequiredTypeDescription
grant_typerequiredstringAs defined in the OAuth 2.0 specification, this field must contain a value of client_credentials

Request example:

curl --request POST 'https://ExampleDomain.admin.cogito.us/api-ext/domain/ExampleDomain/token'\
 --header 'Authorization: Basic Zm9vOmJhcg==' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials'

Response example:

A successful response will return HTTP Status 200 OK with JSON body.

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "token_type": "Bearer",
  "expires_in": 3600
}

Response fields:

NameRequiredTypeDescription
acess_tokenrequiredstringThe access token in JWT format issued by the authorization server
token_typerequiredstringThe type of the token issued. Always set to Bearer. Value is case insensitive
expires_inrequiredintegerThe lifetime in seconds of the access token. For example, the value 3600 denotes that the access token will expire in one hour from the time the response is generated