#OAuth 2.0

OAuth 2.0 is an open standard for authorization and works over HTTPS. In Setu's context, it can be used in two different occassions.

• Merchant can authorize Setu requests for BBPS
• Setu can authorize merchant's requests to Setu Reports API

Read more about OAuth 2.0 here ↗.

#Setu consuming Merchant OAuth Token API

Setu will make a request to the Token URL with the credentials configured on Bridge under the OAuth2.0 Auth scheme.

Assume the URLs to be

• Base URL: https://api.my-company.com/v1/bbps
• Token URL: https://api.my-company.com/v1/bbps/auth/oauth

Based on the chosen OAuth2.0 scheme on Bridge, Setu will make either one of the following requests

• For Client credentials

    curl --location --request POST 'https://api.my-company.com/v1/bbps/auth/oauth' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=client_credentials' \
    --data-urlencode 'client_secret=myOAuthSecret' \
    --data-urlencode 'client_id=myClientID'
    

{
      "access_token": "actual_token", 
      "refresh_token": "token_used_to_refresh_access_token"
}

• For Password

    curl --location --request POST 'https://api.my-company.com/v1/bbps/auth/oauth' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'username=myUsername' \
    --data-urlencode 'password=myPassword' \
    --data-urlencode 'grant_type=password' \
    --data-urlencode 'client_secret=myOAuthSecret' \
    --data-urlencode 'client_id=myClientID'
    

{
      "access_token": "actual_token", 
      "refresh_token": "token_used_to_refresh_access_token"
}

This access_token would then be used to make /bills/fetch and /bills/fetchReceipt requests to the Base URL configured on Bridge as follows.

curl --location --request POST 'https://api.my-company.com/v1/bbps/bills/<fetch||fetchReceipt>' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <access_token>' \
    --data '{......}'
    

#Calling Setu-hosted APIs for Reports

A merchant calls Setu hosted APIs for fetching reports. Merchants can use OAuth keys to generate an access token and authorize such API requests with the generate token API explained below.

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

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