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

Setting up oAuth2.0 API Client

- Generate API Client Credentials:

- Edit/Deactivate API Client

For detailed information, see API Authentication.

1. Login to Capillary Intouch Portal

2. Go to Organization Settings

3. Search for Authentication

4. Click on New API Client

5. Enter following details:

   1. Client name - Name of integration project

   2. Description - Description of integration project

   3. Token expiry duration - maximum 60 minutes

   4. Default till - A till which can be used as fallback to attribute any data operations

   5. Access permissions - Entity wise read/write permissions

6. Click Done to generate Client Key and Client Secret

7. 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

{

  "key": "WnCygRI1Fmlf6YudKyTxQq1LI",

  "secret": "2N41LImw48BG6IqXGeZY2XaxW6JLin0AVwQjYTzA"

}

Response

Case 1 - If client credentials are valid

{

    "data": {

     "accessToken": "eyJraWQiOiJrMSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJDYXBpbGxhcnkiLCJleHAiOjE1NzUyNzAyNzAsImp0aSI6IjJaX2FqUjcwYzJABChVUjlDVTVpUlEiLCJpYXQiOjE1NzUyNjk5NzAsInN1YiI6Im5hbWVfODQzNjIwODIwMSIsImNsaWVudF9pZCI6MjEsIm9yZ19pZCI6MTExNSwidG9rZW5fdXNlIjoidG9rZW5fYWNjZXNzIn0.Ala1-XTDlPtrHFQfCtJKsXe3h_WVyq4QOGI3ZnLNJqOa-<span class="fr-marker" data-id="0" data-type="false" style="display: none; line-height: 0;"></span><span class="fr-marker" data-id="0" data-type="true" style="display: none; line-height: 0;"></span>yJc1UPGbypUysWemzEaiQC_BJ0n9G68SYkVZGi4CSVOhHRNA_dILe8y1Sa90YZKwHVHogJmIKzLmksJrTbjn8s8hSMePBaaUcEdUZ1XssxdFrZhEHHN1fWVYtkdb74PB3sZ7OMDqKUysON8YTNQxLgKOJ3kq0o2QUUDQo1q3gxXFuswate6-jj3oBkcdd1ohhXkPIWZlAb_1lRcLr-ECaaBfh473gayeMVV_6khdKJ7cXrUQ3CXppkrPIzBb7rS6I93iWZw0IlmWbaGduTmPPOhLX6HZLOb84Y28st-cw",

        "ttlSeconds": 300

    },

    "errors": null

}

Case 2 - If client credentials are invalid

{

    "data": null,

    "errors": [

        {

            "code": 320001,

            "message": "Invalid client key and secret"

        }

    ]

}

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

{

  "root": {

    "customer": [

      {

        "mobile": "91700000000",

        "email": "tom.sawyer@example.com",

        "external_id": "XYPZ001",

        "firstname": "Tom",

        "lastname": "Sawyer"

      }

    ]

  }

}

Response

Case 1 - If access token is valid

{

  "response": {

    "status": {

      "success": "true",

      "code": "200",

      "message": "SUCCESS"

    },

    "customers": {

      "customer": [

        {

          "user_id": "XXXXXXXX",

          "mobile": "91700000000",

          "email": "tom.sawyer@example.com",

          "external_id": "XYPZ001",

          "registered_on": "2019-09-11 11:11:11",

          "item_status": {

            "success": "true",

            "code": "1000",

            "message": "Customer Registration Successful"

          }

        ]

     }

   }

}

Case 2 - If token is invalid

{

  "response": {

    "status": {

      "success": "true",

      "code": "401",

      "message": "Unauthorized"

    },

    “customers” : null

}

Case 3 - If token is expired

{

  "response": {

    "status": {

      "success": "true",

      "code": "498",

      "message": "Token expired at 2019-12-02T12:31:15.000+0530""

    },

    “customers” : null

}

Case 4 - If token is valid but does not have access to the requested resource

{

    "response": {

        "status": {

            "code": 403,

            "message": "Client doesn't have access to the requested resource",

            "success": false,

            "warnings": {

                "warning": []

            }

        }

    }

}

Regenerate New Token on Token Expiry 

If API response gives error code 498, token need to be generated again.