Platforms | oAuth 2.0 API Client for Backend Integrations
Harsha Vardhan
started a topic
8 months ago
Introduction
oAuth 2.0 API Client flow allows authorizing server-to-server integrations using temporary access tokens (called JWT). Examples of server-to-server integrations include any custom integration service to update data in Capillary or to generate a report; any integration with a 3rd party server such as an ecommerce, marketing or survey platform; centralized POS integration where API requests come from an API gateway, etc. oAuth 2.0 can be set up by creating an API client credential (Client Key and Secret) with a token expiry duration and API read/write permissions. This credential is then used for generating temporary access tokens. The existing Till User Name (TUN) and Password based basic authentication will continue to exist. Depending on the type of integration, oAuth 2.0 or basic auth can be used.
When to Use Basic v/s oAuth 2.0
Basic
oAuth 2.0
Shall be used for POS integrations where API requests come to Capillary server directly from POS front end or POS store server
Shall be used for backend to backend integrations e.g. POS integrations where API requests come to Capillary server from API gateway or a central server, FTP integrations where backend service need to be authenticated, 3rd party integration where API requests come to Capillary from a backend platform
Harsha Vardhan
Introduction
oAuth 2.0 API Client flow allows authorizing server-to-server integrations using temporary access tokens (called JWT). Examples of server-to-server integrations include any custom integration service to update data in Capillary or to generate a report; any integration with a 3rd party server such as an ecommerce, marketing or survey platform; centralized POS integration where API requests come from an API gateway, etc. oAuth 2.0 can be set up by creating an API client credential (Client Key and Secret) with a token expiry duration and API read/write permissions. This credential is then used for generating temporary access tokens. The existing Till User Name (TUN) and Password based basic authentication will continue to exist. Depending on the type of integration, oAuth 2.0 or basic auth can be used.
When to Use Basic v/s oAuth 2.0
Basic
oAuth 2.0
Shall be used for POS integrations where API requests come to Capillary server directly from POS front end or POS store server
Shall be used for backend to backend integrations e.g. POS integrations where API requests come to Capillary server from API gateway or a central server, FTP integrations where backend service need to be authenticated, 3rd party integration where API requests come to Capillary from a backend platform
Setting up oAuth2.0 API Client
- Generate API Client Credentials:
- Edit/Deactivate API Client
For detailed information, see API Authentication.
Login to Capillary Intouch Portal
Go to Organization Settings
Search for Authentication
Click on New API Client
Enter following details:
Description - Description of integration project
Token expiry duration - maximum 60 minutes
Default till - A till which can be used as fallback to attribute any data operations
Access permissions - Entity wise read/write permissions
Click Done to generate Client Key and Client Secret
Click Copy client secret, as it will not be showed in the UI again
- Edit/Deactivate API Client
Once created, the API Client can be edited or deactivated from Organization Settings.
- Disable Basic Authentication
Basic authentication can be disabled or enabled from the Authentication page in Organization Settings.
Authenticating with Client Credentials
Refer to the API documentation for detailed information.
Generate access token with client credentials.
Generate JWT token by calling token/generate API with client credentials
Sample Request
URL - {URL}/v3/oauth/token/generate
Method - POST
Headers - Not required
Body
Response
Case 1 - If client credentials are valid
Case 2 - If client credentials are invalid
Request API with Access Token
Call any API with JWT token using the header “X-CAP-API-ATTRIBUTION-TILL”
Till code can be passed in the header “X-CAP-API-OAUTH-TOKEN”, else default till will be used to mark any data writes and updates.
Sample Request
URL - {URL}/v1.1/customer/add?format=json
Method - POST
Headers
X-CAP-API-ATTRIBUTION-TILL: “blr.koramangala.till001”
X-CAP-API-OAUTH-TOKEN : "eyJraWQiOiJrMSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJDYXBpbGxhcnkiLCJleHAiOjE1NzUyNzEwMjgsImp0aSI6Im9aczQyNUtUVF93SGFtYVFXdnZFQ1EiLCJpYXQiOjE1NzUyNzA3MjgsInN1YiI6Im5hbWVfODQzNjIwODIwMSIsImNsaWVudF9pZCI6MjEsIm9yZ19pZCI6MTExNSwidG9rZW5fdXNlIjoidG9rZW5fYWNjZXNzIn0.twzL9DRws-8C6XfBf3pzu5KpBtvIhoL1Wq2VbLHFYpT032s23QnN2oHGEtQ-rjYgEalpytMK-lsnAl0fqJTpHdbR0lAB_sqQT4EQWAlC1ysbZTEaL7JBMHYxVprZsWWsSDdizgglr35hSq6tKlkID2onDkkZyAgS2CpZUfCArsacXsPB4RhCNGW-dYTdQ2chiGczCU12yBkd0qNEeduSm7BgCHPcimmTqHy91DvQ8sGLluj0XkJ7dq2xfM5FPbnHQJivbW8ku1L5ow4yxiA6IxjLrgeUNwyydIBG4JPL3it3jDuHY_2_1129crlWtsMR1zztWNaT4eh1EMJnNMivdg"
Body
Response
Case 1 - If access token is valid
Case 2 - If token is invalid
Case 3 - If token is expired
Case 4 - If token is valid but does not have access to the requested resource
Regenerate New Token on Token Expiry
If API response gives error code 498, token need to be generated again.