Authentication

Catenda APIs support the following OAuth 2.0 authentication methods:

Use the following endpoints to authenticate with Catenda APIs.

Authorize endpoint

https://api.catenda.com/oauth2/authorize

Token endpoint

https://api.catenda.com/oauth2/token

Authorization Code Grant

The Authorization Code Grant is the most common OAuth 2.0 flow. It is used when an application needs to access resources on behalf of a Catenda Hub user. For additional security or in situations where the client secret can not be stored securely, you can use the Proof Key for Code Exchange (PKCE) extension.

1. Obtaining an authorization code

First, you will need to obtain an authorization code by redirecting the user to the authorize endpoint with the following query parameters.

Name

Type

Description

client_id

String

The client_id of the application making the request

response_type

String

Value must be code

response_mode

String

Valid values are query or fragment, default is query

state

String

Additional state included in the response which may be useful for your application

redirect_uri

String

The registered redirect URI of the application where the response will be sent

prompt

String

Whether Catenda will always prompt users to login or be remembered on future visits. Valid values are login and none

Example

URL


If the user is successful and allows access to your application, Catenda will redirect back to the redirect URI with the following query parameters.

Name

Type

Description

code

String

The authorization code

state

String

State included in initial request

Obtaining an authorization code (PKCE)

To enable PKCE for your application you must contact Catenda Support .

You can use the Proof Key for Code Exchange (PKCE) extension to enhance the security of the Authorization Code Grant flow.

For this flow you will need to generate a code challenge and a code verifier. The code verifier is a client generated cryptographically random string using the characters A-Z, a-z, 0-9, and the punctuation characters -.\_~, between 43 and 128 characters long. The code challenge is created by SHA256 hashing the code verifier.

Follow the Authorization Code Grant flow above with the following additional parameters.

Name

Type

Description

code_challenge

String

The code challenge is created by SHA256 hashing the code verifier

code_challenge_method

String

The method used to generate the code challenge. Valid values are S256

Example

URL


2. Obtaining an access token

Once you have an authorization code you will need to exchange it for an access token using the token endpoint with the following parameters.

Name

Type

Description

client_id

String

The client id of the application

client_secret

String

The client secret of the application

code

String

The authorization code

grant_type

String

Value is authorization_code

redirect_uri

String

The registered redirect URI

Example

Curl


If the request is valid Catenda will reply with the following response.

Name

Type

Description

access_token

String

The access token

refresh_token

String

The refresh token

token_type

String

Type of the token, valid value is bearer

expires_in

Integer

Time until token expires in seconds

Obtaining an access token (PKCE)

Instead of providing the client_secret you must include the following additional parameters.

Name

Type

Description

code_verifier

String

Client generated cryptographically random string using the characters A-Z, a-z, 0-9, and the punctuation characters -.\_~, between 43 and 128 characters long

Example

Curl


3. Refreshing an access token

Access tokens expire after one hour, you can request a new access token using the token endpoint with the following parameters.

Name

Type

Description

client_id

String

The client id of the application

client_secret

String

The client secret of the application

grant_type

String

Value is refresh_token

refresh_token

String

The refresh token

Example

Curl


If the request is valid Catenda will reply with the following response.

Name

Type

Description

access_token

String

The access token

refresh_token

String

The refresh token

token_type

String

Type of the token

expires_in

Integer

Time until token expires in seconds

The response includes a new refresh token and the previous access and refresh tokens become invalid.

Refreshing an access token (PKCE)

Omit the client_secret parameter.

Example

Curl


Client Credentials Grant

The Client Credentials Grant is used when an application needs to access resources on behalf of itself. This flow is typically used for server-to-server communication.

Client Credentials Grant is only available for Catenda Boost customers.

1. Obtaining an access token

Request an access token using the token endpoint with the following parameters.

Name

Type

Description

client_id

String

The client id of the application

client_secret

String

The client secret of the application

grant_type

String

Value is client_credentials

Example

Curl


If the request is valid Catenda will reply with the following response.

Name

Type

Description

access_token

String

The access token

token_type

String

Type of the token

expires_in

Integer

Time until token expires in seconds