Step 1—Login to the Bridge and head to Org settings
OAuth keys are created and managed at the organisation level. Currently only the Admin can create keys.
Click on the “Org settings” icon on the left navbar. Here, if you are an Admin, you should see the API keys card. Click on OAuth, which is our recommended protocol.
Step 2—Configure key details
You should be greeted by an empty page, nudging you to generate your first key. Click on the “Generate your first key” button. Now you should see a simple form like the one in the image below.
Select environment—A key can exist only in one environment. Sandbox keys access only sandbox configs, and production keys access only production configs.
Keep in mind that once a key is generated, it cannot change environments later.
Key name—This is just for you to easily identify a key and tell what a particular key can access.
For example, a name like “Bangalore Schools—Setu BBPS” would indicate that the key has access to the school billers configured on the BBPS product, specifically in the Bangalore region.
Add products—This is where you can select the individual product configurations that this key can access.
Click the “Add products” button. The info panel opens on the right, with all your configured products in the selected environment grouped by type. You can also search for a particular product by name or ID.
Clicking on a product tile adds it to the list, which you can see reflected on the main UI. Add and remove products as you wish, and close the info panel when satisfied.
Step 3 — Generate the key
Now the “Generate key” button should become enabled, after all the fields are filled. Click it, and you should see the clientID and secret for this key.
And done! You are now all set to use this key to make API requests to Setu. The key should also now be listed on the API keys main page, at the very top.
In case a key is compromised at any point, you can regenerate the clientID and the secret for that key easily on the Bridge.
Click on the key to go to the Edit key page, and scroll down to the Credentials section. Click on the “Regenerate key” button. You will be asked for confirmation twice, as key regeneration cannot be undone.
Once you confirm, the old credentials would stop working, and be deleted, and a fresh clientID and secret would be generated for you to use. The name of the key and the products it can access are not affected.
This process is independent and instant, and does not need the “Save changes” button to be clicked.
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.
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>.
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.