#OAuth 2.0

OAuth 2.0 is an open standard for authorisation and works over HTTPS. In Setu's context, it is used to authorise API requests with access tokens. Read more about OAuth 2.0 here ↗.

For Setu products, OAuth keys provide a lot of flexibility—you can setup a single set of keys to authorise requests for multiple product configurations, or authorise requests for a single configuration using multiple sets of keys.

#Calling Setu-hosted APIs

A merchant calls Setu hosted APIs for creating payment links, checking link status, for fetching reports etc. Merchants can use OAuth keys to generate an access token and authorise such API requests with the generate token API explained below.

Note on JWT authentication

The generate token API works only with OAuth keys. If you have implemented JWT auth to call Setu hosted APIs, we recommend upgrading to OAuth soon. We support JWT auth but will not build any further features for it.

Change of URLs for OAuth

#How to get OAuth keys

Step 1—Login to The Bridge and head to Org settings

If you are an Admin for your Bridge account, you should be able to see the API keys card under “Org settings” in the left panel. Click the OAuth keys card to view keys for all your product configs.

Step 2—Configure key details

On clicking “Generate new key”, you should see a simple form

Select environment—A key can exist only in one environment. Sandbox keys access only sandbox configs, and production keys access only production configs.

Key name—This is for you to easily identify a key later and tell what a particular key can access.

Add products—Here's where you can select the product configurations that this key can access.

Step 3—Generate key

The “Generate key” button is enabled once all the fields are filled. Click it, and you should see the clientID and secret for this key.

And done! You can now use this key to make API requests to Setu. Read more ↗ on supported features for OAuth keys.

#Generate Token API

An API to generate tokens, which are used to authorise any other API requests made to Setu. This API works with OAuth keys only.

Request

Request body

{
    "clientID" : "c0a411d5-b6f9-4bfd-a342-7cb01935ed43",    
    "secret"   : "b2b3e650-a31b-47a3-acf6-c96c9c5c282d",
}

Response

Success

A new token is provided by Setu in the success response, along with an expiresIn param, which states the validity of the token in seconds (the present default value is 1800 seconds or 30 minutes). You may store and keep reusing the same token till it expires.

{
    "status" : 200,
    "success" : true,
    "data" : {
        "expiresIn" : 1800, //seconds
        "token"     : "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJsaWJ6NGFNaE4yUk5xMlpyVk9QaFhaMXpoMjA0V2gtdTdhT21LX2huRVQ4In0.eyJleHAiOjE2MTM5OTQzMTIsImlhdCI6MTYxMzk5NDAxMiwianRpIjoiZmZhZjM2ZTUtZmI3Mi00NTY2LTljOGYtY2U5N2I5MjY2Y2E4IiwiaXNzIjoiaHR0cHM6Ly9hdXRoLWRldi5zZXR1LmNvL2F1dGgvcmVhbG1zL2NvbGxlY3QiLCJzdWIiOiJhZGE1MTNhMS0xYjVhLTQ1NGQtYTk2Ny05OGI3YTYwNjY3MTAiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJjZDRlYTM5OC03YWIzLTQ3ZGUtYWE1MC03YzNiOWIzZjBhMjYiLCJzZXNzaW9uX3N0YXRlIjoiYmYxYjJjZjgtNTgzZC00Y2MwLWIwN2QtNmI5YWQyNmZiNGI0IiwiYWNyIjoiMSIsInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwiY2xpZW50SWQiOiJjZDRlYTM5OC03YWIzLTQ3ZGUtYWE1MC03YzNiOWIzZjBhMjYiLCJjbGllbnRIb3N0IjoiMTA2LjUxLjE1LjI1MCIsIlgtU2V0dS1Qcm9kdWN0LUluc3RhbmNlLUlEIjoiNTYyNDMzODMwNDMwOTY2OTk4IiwicHJlZmVycmVkX3VzZXJuYW1lIjoic2VydmljZS1hY2NvdW50LWNkNGVhMzk4LTdhYjMtNDdkZS1hYTUwLTdjM2I5YjNmMGEyNiIsImNsaWVudEFkZHJlc3MiOiIxMDYuNTEuMTUuMjUwIn0.QfEzImuN1P9jwTBJTcJ6ozP_gC3J-FOJp0D0va2AfXUUw8d5HLA5zqojCd6BnE6ApqKWnVU1aB0YWFwDbgHaVA3Netr-hmGadElLMhGiHah2UaLO0Bk86pZpyxNxtdx9u6YjfVYT6TSvUsqO4lISegFTJRTqFZxuBFv4WoKJPPD0JwEMYGH71LyOiCJA2sAq4YbOMKOvRrj2X_ipkSqvsrgEZicJ3lTY4vWyoGJ8wps0VW6k4vFSdX1qRKrAz_7XVKr8MKz_H1ng91h5XlZqsUh6BPz3WW0atWjt0RbAtXR32iB0zaB204IECxwriNmka1FxA9PZq94NvPwANDznhQ"
    }
}

Failure

If incorrect clientID and secret details are provided, Setu could respond with the following error—

{
    "status"  : 400,
    "success" : false,
    "error" : {
        "code"    : "invalid-api-key",
        "detail"  : "API key invalid [cd4ea398-7ab3-47de-aa50-7c3b9b3f0a21], please recheck your credentials.",
        "docURL"  : "",
        "title"   : "AUTHENTICATION_ERROR"
        "traceID" : "8b7bd233-5231-4bdd-8d48-aa4c0dae07b9"
        "errors"  : [],
    }
}

• The traceID in the above response is dynamic and can be shared with Setu support team, if further debugging is required.

#How to use the token

Once you have a valid token available against product configuration(s), you can store it and use it to authorise an API call made to Setu, by setting the authorization request header as Bearer <token-value>.

On expiry

Implement a workflow to generate new token when the old one expires. The general setup might look something like this—

• Store clientID and secret.
• Generate new token with stored clientID and secret when token has expired. If the API you call returns 401 unauthorized, it could be an indication that the token has expired.
• Store the newly generated token and use for subsequent API calls.