Authentication

catenda apis support the following oauth 2 0 authentication methods authentication /#authorization code grant authentication /#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=\&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) 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 url 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 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 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 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 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 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