Authentication

Catenda APIs support the following OAuth 2.0 authentication methods:
﻿Authorization Code Grant﻿﻿
﻿Client Credentials Grant﻿﻿
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
http://api.catenda.com/oauth2/authorize?client_id=<CLIENT_ID>&response_type=code&redirect_uri=<REDIRECT_URI>
http://api.catenda.com/oauth2/authorize?client_id=<CLIENT_ID>&response_type=code&redirect_uri=<REDIRECT_URI>
﻿
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
http://api.catenda.com/oauth2/authorize?client_id=<CLIENT_ID>&response_type=code&redirect_uri=<REDIRECT_URI>&code_challenge_method=S256&code_challenge=<CODE_CHALLENGE>
http://api.catenda.com/oauth2/authorize?client_id=<CLIENT_ID>&response_type=code&redirect_uri=<REDIRECT_URI>&code_challenge_method=S256&code_challenge=<CODE_CHALLENGE>
﻿
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
curl --request POST \
  --url https://api.catenda.com/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_id=<CLIENT_ID> \
  --data client_secret=<CLIENT_SECRET> \
  --data code=<AUTHORIZATION_CODE> \
  --data grant_type=authorization_code \
  --data redirect_uri=<REDIRECT_URI>
curl --request POST \
  --url https://api.catenda.com/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_id=<CLIENT_ID> \
  --data client_secret=<CLIENT_SECRET> \
  --data code=<AUTHORIZATION_CODE> \
  --data grant_type=authorization_code \
  --data redirect_uri=<REDIRECT_URI>
﻿
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
curl --request POST \
  --url https://api.catenda.com/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_id=<CLIENT_ID> \
  --data code=<AUTHORIZATION_CODE> \
  --data code_verifier=<CODE_VERIFIER> \
  --data grant_type=authorization_code \
  --data redirect_uri=<REDIRECT_URI>
curl --request POST \
  --url https://api.catenda.com/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_id=<CLIENT_ID> \
  --data code=<AUTHORIZATION_CODE> \
  --data code_verifier=<CODE_VERIFIER> \
  --data grant_type=authorization_code \
  --data redirect_uri=<REDIRECT_URI>
﻿
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
curl --request POST \
  --url https://api.catenda.com/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_id=<CLIENT_ID> \
  --data client_secret=<CLIENT_SECRET> \
  --data grant_type=refresh_token \
  --data refresh_token=<REFRESH_TOKEN>
curl --request POST \
  --url https://api.catenda.com/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_id=<CLIENT_ID> \
  --data client_secret=<CLIENT_SECRET> \
  --data grant_type=refresh_token \
  --data refresh_token=<REFRESH_TOKEN>
﻿
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
curl --request POST \
  --url https://api.catenda.com/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_id=<CLIENT_ID> \
  --data grant_type=refresh_token \
  --data refresh_token=<REFRESH_TOKEN>
curl --request POST \
  --url https://api.catenda.com/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_id=<CLIENT_ID> \
  --data grant_type=refresh_token \
  --data refresh_token=<REFRESH_TOKEN>
﻿
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
curl --request POST \
  --url https://api.catenda.com/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_id=<CLIENT_ID> \
  --data client_secret=<CLIENT_SECRET> \
  --data grant_type=client_credentials
curl --request POST \
  --url https://api.catenda.com/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_id=<CLIENT_ID> \
  --data client_secret=<CLIENT_SECRET> \
  --data grant_type=client_credentials
﻿
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
﻿

Authorize endpoint	https://api.catenda.com/oauth2/authorize
Token endpoint	https://api.catenda.com/oauth2/token

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

Name	Type	Description
code	String	The authorization code
state	String	State included in initial request

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

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

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

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

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

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

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

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

Updated 19 Jun 2024

Did this page help you?

Creating an Application

Error Handling