Authentication with OAuth 2.0

Cogito APIs Activation

Usage of the Cogito APIs first requires customers to choose between a production or lab environment and request activation of the API. This process involves working with your Cogito Customer Success Manager (CSM) or Program Manager to submit a request for enabling the Cogito APIs in the selected environment.

Upon provisioning the API, Cogito will send an encrypted email containing the Client ID and Secret credentials necessary for accessing the requested APIs.

API Authentication

Cogito APIs utilize OAuth 2.0 protocol 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

Once Cogito has issued client_id and client_secret per above, you can then use this information to retrieve the OAuth 2.0 access token that will be used for all subsequent Cogito APIs.

Endpoint

POST auth/realms/{domain}/protocol/openid-connect/token HTTP/1.1
Host: auth.{domain}.cogito.us

Path Parameters

Name	Required	Type	Description
domain	required	string	Client's unique tenant name

Header

Name	Required	Description
content-type	required	Must be application/x-www-form-urlencoded
authorization	required	Basic authorization formed by base64 encoding the issued client_id and client_secret

Body Parameters

Name	Required	Type	Description
grant_type	required	string	As defined in the OAuth 2.0 specification, this field must contain a value of client_credentials

Request example:

curl --request POST 'https://auth.ExampleTenant.cogito.us/auth/realms/ExampleTenant/protocol/openid-connect/token HTTP/1.1'\
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic Zm9vOmJhcg==' \
--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:

Name	Required	Type	Description
access_token	required	string	The access token in JWT format issued by the authorization server
token_type	required	string	The type of the token issued. Always set to Bearer. Value is case insensitive
expires_in	required	integer	The 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