OAuth

This page provides you with information on how to authenticate APIs using OAuth.

When using OAuth, the API client key and secret key or an access token are used for calling APIs, rather than the user's credentials. This enhances security by avoiding misuse of user's credentials and creates secure pathways for accessing your organization's data via Capillary APIs.

Creating API client key and secret

API client key and secret can be created from the Authentication page in the organization settings. Refer to documentation Create an API client key and secret.

Generating access token

Prerequisite : API client key and secret.

Once you get the key and secret, you can generate an 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 endpoint

ParameterValue
URI/oauth/token/generate
API versionv3
HTTP methodPOST
Authentication RequiredNo
Batch SupportNo

Header

Content-Type: application/json

POST request schema

https://eu.api.capillarytech.com/v3/oauth/token/generate
{
  "key": "",
  "secret": ""
}

Example:

https://eu.api.capillarytech.com/v3/oauth/token/generate
{
  "key": "WnCygRI1Fmlf6YudKwTxQq1LI",
  "secret": "hoqSBz6VwefECaZA8Q3oNx4V4H3pMDITksarZVES"
}
{
    "data": {
     "accessToken": "eyJraWQiOiJrMSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJDYXBpbGxhcnkiLCJleHAiOjE1NzUyNzAyNzAsImp0aSI6IjJaX2FqUjcwYzJABChVUjlDVTVpUlEiLCJpYXQiOjE1NzUyNjk5NzAsInN1YiI6Im5hbWVfODQzNjIwODIwMSIsImNsaWVudF9pZCI6MjEsIm9yZ19pZCI6MTExNSwidG9rZW5fdXNlIjoidG9rZW5fYWNjZXNzIn0.Ala1-XTDlPtrHFQfCtJKsXe3h_WVyq4QOGI3ZnLNJqOa-yJc1UPGbypUysWemzEaiQC_BJ0n9G68SYkVZGi4CSVOhHRNA_dILe8y1Sa90YZKwHVHogJmIKzLmksJrTbjn8s8hSMePBaaUcEdUZ1XssxdFrZhEHHN1fWVYtkdb74PB3sZ7OMDqKUysON8YTNQxLgKOJ3kq0o2QUUDQo1q3gxXFuswate6-jj3oBkcdd1ohhXkPIWZlAb_1lRcLr-ECaaBfh473gayeMVV_6khdKJ7cXrUQ3CXppkrPIzBb7rS6I93iWZw0IlmWbaGduTmPPOhLX6HZLOb84Y28st-cw",
        "ttlSeconds": 300
    },
    "errors": null
}

Response

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.

Using access token

Once you generate the access token, you can use it to authenticate API calls as shown below.

Set the authentication to No Auth and pass the following headers.

HeaderValue
X-CAP-API-OAUTH-TOKEN*Generated access token.
Content-Type*This should be set as application/json
Accept*This should also be set as application/json
X-CAP-API-ATTRIBUTION-ENTITY-TYPETill or store from which you want to post the data. Supported Values: TILL, STORE_CODE, STORE_NAME, STORE_EXTERNAL_ID, STORE_EXTERNAL_ID_1, STORE_EXTERNAL_ID_2. The default value is TILL.
X-CAP-API-ATTRIBUTION-ENTITY-CODEPass the entity value based on the entity type. For example, if X-CAP-API-ATTRIBUTION-ENTITY-TYPE is STORE_CODE, then X-CAP-API-ATTRIBUTION-ENTITY-CODE is the store code that you want to tag to POST data. By default, it considers the Till associated with the client key and secret.

Error Handling

ErrorProbable causeRecommended action
Failed to generate OAuth token- Client key or secret invalid - Insufficient permission to access group- Ensure the auth key and secret are correct. - Ensure you have right permissions to the appropriate access group. To know more about access group, see Access group