OAuth provides better security and helps you create secure passages to access your org's data through Capillary APIs. You can generate an API client credential (client key and secret) with read/write access to one or more resources. Once you get the credentials, you can generate an access token using step 1 mentioned on this page.

oAuth 2.0 API Client Flow provides the server-to-server authorization with a temporary access token. Examples of server-to-server integrations include custom integration service to update data in Capillary or to generate a report; 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.  

An org can have up to 15 API client accounts.

The following sections provide detailed steps involved in creating client API accounts and access tokens.

Step 1: Get Client Key and Secret

For any integration through OAuth, you need your Client Key and Client Secret. Capillary Admin can create these on the Admin page of InTouch. 

  1. Log on to InTouch of your cluster 
  2. Navigate to <Path>
  3. Click Register to create a new client (token key and secret) for the org.

  1. In Client name, enter a name for the client.

  1. In Description, enter a short description of the client.
  2. In Token expiry duration, set the default expiry (in minutes) for the tokens created for the client. To modify, drag the pointer to the required position on the line.
  3. In Access Permission, select the desired access that you want to provide for the current client - Target Groups: Related to target loyalty APIs; Transaction: Related to transaction API; All: For all other APIs.
  • None: To restrict both read and write access to the respective APIs. This is the default value.
  • View only: Select this to provide only read access to the respective APIs.
  • Modify: Select this to provide both read and write access (add/update) to the respective APIs.
  1. In Select your organization till, choose the Till that you want to associate to all the POST API calls.
  2. Click Next. You will see the Client key and Client secret generated for the client.

  1. Copy the Client key and client secret and use it for authentication (OAuth). Using these details, you can also generate access token through API as mentioned in the next section (Step 2: Generate Access Token).

  1. Click Done to close the screen.
  2. To create more API client accounts, use New API Client. You can create up to 15 accounts for an org.

After the client key and secret are generated, if you exit the API Credentials page, you cannot access the client secret again for that client.

Step 2: Generate Access Token

Once you get key and secret, you can generate access token or JWT (JSON Web Token) using the token/generate API. JWT is a compact URL and JSON-based used to transfer data securely between two parties.

The token validity will be as per the value set for the client (Token expiry duration). If a token expires, you can regenerate it using the same API.


Resource Information

URI/oauth/token/generate
API Versionv3
HTTP MethodPOST
Authentication Required?No
Batch Support?No

Endpoint

https://{host}/v3/oauth/token/generate

Request Body Parameters

ParameterDatatypeDescription
keystringClient key generated for the account. For more details, see step 10 in the previous section.
secretstringClient secret generated for the account. For more details, see step 10 in the previous section.
{
  "key": "",
  "secret": ""
}

Response Parameters

ParameterDescription
accessTokenGenerated access token for the given key and secret. This is unique and varies every time you make the call.
ttlSecondsThe validity of the token in seconds.

Example

Sample URL

https://eu.api.capillarytech.com/v3/oauth/token/generate

Sample Request

{
  "key": "WnCygRI1Fmlf6YudKwTxQq1LI",
  "secret": "hoqSBz6VwefECaZA8Q3oNx4V4H3pMDITksarZVES"
}

Sample Response (In case of valid credentials)

{
    "data": {
     "accessToken": "eyJraWQiOiJrMSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJDYXBpbGxhcnkiLCJleHAiOjE1NzUyNzAyNzAsImp0aSI6IjJaX2FqUjcwYzJABChVUjlDVTVpUlEiLCJpYXQiOjE1NzUyNjk5NzAsInN1YiI6Im5hbWVfODQzNjIwODIwMSIsImNsaWVudF9pZCI6MjEsIm9yZ19pZCI6MTExNSwidG9rZW5fdXNlIjoidG9rZW5fYWNjZXNzIn0.Ala1-XTDlPtrHFQfCtJKsXe3h_WVyq4QOGI3ZnLNJqOa-yJc1UPGbypUysWemzEaiQC_BJ0n9G68SYkVZGi4CSVOhHRNA_dILe8y1Sa90YZKwHVHogJmIKzLmksJrTbjn8s8hSMePBaaUcEdUZ1XssxdFrZhEHHN1fWVYtkdb74PB3sZ7OMDqKUysON8YTNQxLgKOJ3kq0o2QUUDQo1q3gxXFuswate6-jj3oBkcdd1ohhXkPIWZlAb_1lRcLr-ECaaBfh473gayeMVV_6khdKJ7cXrUQ3CXppkrPIzBb7rS6I93iWZw0IlmWbaGduTmPPOhLX6HZLOb84Y28st-cw",
        "ttlSeconds": 300
    },
    "errors": null
}


Sample Response (In case of invalid key or secret)

{
    "data": null,
    "errors": [
        {
            "code": 320001,
            "message": "Invalid client key and secret"
        }
    ]
}

Step 3: Make API Call with Access Token

You can use JWT to make any API request. To make an API call, you need to include the following headers and the respective API details (U)users t

Headers Required

X-CAP-API-OAUTH-TOKEN*The generated access token.
Content-Type*Media type of the request to send from client to server. It is usually application/json.
Accept*Media type of the response content. It is usually application/json.
X-CAP-API-ATTRIBUTION-TILL-CODETill code from which you want to POST data. By default, the Till associated with the client key and secret is mapped if this is not passed.

Example

Sample Endpoint

https://eu.api.capillarytech.com/v1.1/customer/add?format=json

Sample Headers

X-CAP-API-ATTRIBUTION-TILL-CODE

“blr.koramangala.till001”

X-CAP-API-OAUTH-TOKEN

"eyJraWQiOiJrMSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJDYXBpbGxhcnkiLCJleHAiOjE1NzUyNzEwMjgsImp0aSI6Im9aczQyNUtUVF93SGFtYVFXdnZFQ1EiLCJpYXQiOjE1NzUyNzA3MjgsInN1YiI6Im5hbWVfODQzNjIwODIwMSIsImNsaWVudF9pZCI6MjEsIm9yZ19pZCI6MTExNSwidG9rZW5fdXNlIjoidG9rZW5fYWNjZXNzIn0.twzL9DRws-8C6XfBf3pzu5KpBtvIhoL1Wq2VbLHFYpT032s23QnN2oHGEtQ-rjYgEalpytMK-lsnAl0fqJTpHdbR0lAB_sqQT4EQWAlC1ysbZTEaL7JBMHYxVprZsWWsSDdizgglr35hSq6tKlkID2onDkkZyAgS2CpZUfCArsacXsPB4RhCNGW-dYTdQ2chiGczCU12yBkd0qNEeduSm7BgCHPcimmTqHy91DvQ8sGLluj0XkJ7dq2xfM5FPbnHQJivbW8ku1L5ow4yxiA6IxjLrgeUNwyydIBG4JPL3it3jDuHY_2_1129crlWtsMR1zztWNaT4eh1EMJnNMivdg" 

Sample POST Body

{
  "root": {
    "customer": [
      {
        "mobile": "91700000000",
        "email": "tom.sawyer@example.com",
        "external_id": "XYPZ001",
        "firstname": "Tom",
        "lastname": "Sawyer"
      }
    ]
  }
}

Sample Response

Case 1: In case of a valid token

If the call is made within the token expiry period, you will get a successful response.

{
  "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: In case of an invalid token

If the token is invalid, you will get the following response. You need to pass a valid token.

{
  "response": {
    "status": {
      "success": "true",
      "code": "401",
      "message": "Unauthorized"
    },
    “customers” : null
}

Case 3: if the token has expired

If the token expires, the call fails with the message Token expired at {time}. In this case, you need to generate the token again and make an API call with the token expiry period.

{
  "response": {
    "status": {
      "success": "true",
      "code": "498",
      "message": "Token expired at 2019-12-02T12:31:15.000+0530""
    },
    “customers” : null
}
If your token has expired (error code: 498), you need to regenerate it as explained in Step 2.

Case 4: if the token is valid but no access to the requested resource

You need to set the access scope for every client account you create as explained in Step 1. If you try to use the token for resources other than that configured, you will get the following error response.

{
    "response": {
        "status": {
            "code": 403,
            "message": "Client doesn't have access to the requested resource",
            "success": false,
            "warnings": {
                "warning": []
            }
        }
    }
}