--- title: Authentication slug: authentication docTags: createdAt: 2024-06-11T11:06:43.519Z --- Catenda APIs support the following [OAuth 2.0](https://www.oauth.com/) authentication methods: - [Authorization Code Grant](./#authorization-code-grant) - [Client Credentials 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** :::CodeblockTabs URL ```html http://api.catenda.com/oauth2/authorize?client_id=&response_type=code&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)** :::hint{type="info"} To enable **PKCE** for your application you must contact [Catenda Support](mailto\:support@catenda.com) . ::: 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** :::CodeblockTabs URL ```html http://api.catenda.com/oauth2/authorize?client_id=&response_type=code&redirect_uri=&code_challenge_method=S256&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= \ --data client_secret= \ --data code= \ --data grant_type=authorization_code \ --data 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= \ --data code= \ --data code_verifier= \ --data grant_type=authorization_code \ --data 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= \ --data client_secret= \ --data grant_type=refresh_token \ --data 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 | :::hint{type="warning"} 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= \ --data grant_type=refresh_token \ --data 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. :::hint{type="info"} Client Credentials Grant is only available for [Catenda Boost customers](https://catenda.com/bim-solutions-open-standards/catenda-boost-bim-api/). ::: ### 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= \ --data 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 |