API client
What is an API client?
An API client is a software application, such as an ERP or a billing system, that is authorized to access protected resources using an access token. When you create an API client, you will receive a client secret that is unique and confidential. Using this client secret, you can generate an access token to access protected resources.
At the time of the creation of the API client, you can choose to restrict the products which can be accessed, IPs from where they can be accessed, and the expiration time of the access token to enable rotation.
What is a client secret?
A client secret is a confidential private key used by an API client, such as an ERP or a billing system, to authenticate itself with the Clear authorization service to generate access tokens.
A client secret is specific to an environment and a workspace. This means, for the Clear sandbox and production environment, you will need a separate client secret. Similarly, if you have multiple workspaces in Clear, you will need a separate client secret.
What is an access token?
An access token is a confidential private key used by an API client, such as an ERP or a billing system, to authenticate itself with Clear products, such as GST, Max ITC, E-Invoice, etc., to access protected resources via API.
What is the difference between a client secret and an access token?
The difference between a client secret and an access token is that a client secret can only be used to generate access tokens, whereas an access token can be used to access protected business resource APIs, such as generating E-Invoices or uploading documents.
How to create an API client secret?
To create an API client secret, you must have a workspace or product administrator access. If you lack this privilege, please contact your Clear account workspace administrator or product administrator.
If you are a workspace or product administrator, follow these steps to create a client secret:
Log in to your Clear sandbox (https://app-sandbox.clear.in) or production (https://app.clear.in) account.
In the bottom left corner, click "Settings".
In the navigation sidebar, go to the "Integrations" tab and click "API Clients".
Click "Create API Client" to open a form.
Choose the workspace for which you want to create the API client.
Choose the products for which you want to create the API client. You can select more than one product if you want to use the same client secret for all of them.
Select the expiration period for the access tokens generated using this client secret. If you don't want the access tokens to expire, select "Never Expires". The minimum expiration period is 5 minutes.
Enter the email address where you want to receive updates and notifications related to any changes to the API client. By default, this will be your logged-in email address. You can add more users from your organization who want to receive the notification.
Enter the IP address that you want to restrict API access to when using this client secret or the access tokens generated using this client secret. This field is optional and provides additional security. If you have multiple NAT gateway IP addresses, you can add them individually or use CIDR (Classless Inter-Domain Routing) notation to add them all at once.
Click "Create API Client," and the client secret will appear below.
Copy the client secret and save it in a safe and secure place in your ERP or billing system, where it will be used to generate access tokens dynamically using the "Generate access token API."
If you have opted to use never expiring access tokens, click the "Generate access token" button to create a one-time generated never expiring access token. Copy this token and store it in a safe and secure place in your ERP or billing system, where it will be used to access business resources directly.
How to use a client secret?
After receiving the client secret, it should be kept in a secure location within your ERP or billing system. Depending on your system, there are different methods to store this key:
For SAP ECC or S/4HANA, a custom table can be created to manage the client secret.
For SAP CPI iflows, the keystore can be used to store the client secret.
For a custom application, the client secret can be kept in Vault, environment variables, or another secure location.
It is important to ensure that only authorized users have access to this storage location. The client secret must be accessible to your application to generate access tokens dynamically via the "Generate access token API."
FAQs
What does "Workspace" mean in the API client creation form?
When you use Clear, all the related products and users are grouped as a workspace. Based on your use case, you may have one or more workspaces. Each workspace is independent with no data sharing across other workspaces. Hence when creating a client secret, you must choose the workspace that the client secret should have access to. If you have only one workspace, you can use the default workspace.
If you are a workspace administrator, you will be able to see all the workspaces that you are an administrator of.
If you are a product administrator, you will be able to see all the workspaces which have products that you are a product administrator of.
Can I change the workspace after creating the client secret?
No, once you have created a client secret, you can not change the workspace. If you do not wish to use the client secret for the selected workspace, you can delete the client secret. If you want to access another workspace via API, you can create a new client secret for that workspace.
What does "Products" mean in the API client creation form?
Clear offers a suite of applications like GST, E-Invoicing, Max ITC, and more. When creating a client secret, you can choose which products the client secret should have access to.
If you are a workspace administrator, you will be able to see all the products under your workspace. Hence you will be able to see all the client secrets created for any of those products in your workspace.
If you are a product administrator, you will be able to see only those products for which you have administrator access. If some other user created or updated a client secret with access to your product in addition to other products that you are not an administrator of, then you will not be able to see this client secret irrespective of who created it.
Do I need to have an active license to select a product?
No, there is no relationship between the client secret creation and license validity.
If you have an active license for each of the selected products, you will be able to use the same client secret for all of them. If you do not have an active license for all of the selected products, you will still be able to use the client secret for the ones where you have a license until it is active.
However, for the products where you do not have an active license, you may get an error in the respective product API. Once the expired license is renewed, the same client secret will work.
Can I change the products after creating the client secret?
Yes, once you have created a client secret, you can edit the client secret to add more products and access those APIs. However, to avoid accidental denial of service, you cannot remove an already selected product. If you wish to remove access to any product, you will have to delete the entire client secret and create a new one with limited product access. This action will revoke all the access tokens generated with that deleted client secret and may affect all the applications using that client secret.
What does "Expiration" mean in the API client creation form?
Your client secret will never expire unless you delete it manually. But for the access tokens generated using the client secret, you can set the expiration period at the time of generation of the client secret itself. Once an access token has expired, you can generate a new access token with the same expiration period starting from that time using the same client secret.
Can I change the expiration after creating the client secret?
Yes, if you have already generated a client secret and want to set the expiration period of the access token later, you can edit the client secret and set or change the expiration period. Please note that changing the expiration period will revoke all the existing access tokens generated using the client secret.
What does "Notification Email ID" mean in the API client creation form?
When a client secret is created, updated, or deleted, it can have security implications. When creating a client secret, you can enter one or more email addresses to receive such notification. The email addresses may belong to another user in the same workspace or maybe a non-user as well (eg: your concerned IT team).
If you created a client secret, and some other administrator removed your email address from the notification list, you will receive an email notification about such an update. However, you will not receive notifications for any subsequent events for that client secret.
Can I change the notification email ID after creating the client secret?
Yes, once you have created a client secret, you can add or remove email addresses for notification at any time in the future. All the email addresses present before updating, and all the email addresses present after updating will receive an email notification about such an update.
What does "IP Whitelisting" mean in the API client creation form?
Once you create a client secret, you will be able to generate an access token and access the business resources of your Clear product. To provide you with an additional layer of security, Clear provides a feature to whitelist an IP address or a set of IP addresses that must be allowed to access the APIs using that client secret. If this field is set, then API requests will be allowed only if originating from the whitelisted IP addresses and all other requests will be disallowed. If you wish to use this feature, make sure to use the public NAT IP from where the requests will be sent out to Clear APIs.
This option is specific to a client secret and will not restrict access via other client secrets. If you have created another client secret to access the same workspace or products without any such IP whitelisting, then you will still be able to access the APIs from any IP address using such client secret.
Can I change the IP addresses after creating the client secret?
Yes, once you have created a client secret, you can add or remove an IP address at any time in the future. This will affect access to the APIs accordingly from that point onwards.
Can I create a single API client secret for multiple ERPs?
Yes, but not recommended. If you have multiple ERP or billing systems, we recommend you create a separate client secret for each system. While you can create a client secret and use the same client secret to make API requests from multiple systems, we highly recommend you use a different client secret for the following security reasons:
Each ERP might be used for a specific product use case and you may not want users of one ERP to be able to access the product resources of another ERP via Clear. Having separate client secrets allows you to restrict products accessible by each client secret.
If a client secret in one ERP is compromised due to a rogue user of that ERP, the security of another ERP will not be compromised.
Can I create multiple API client secrets for the same ERP?
Yes, if you are integrating your ERP with Clear for different products (eg: Max ITC, E-Invoicing), you can create a separate client secret for each product for the same reasons mentioned above.
In case your ERP has multiple instances or pods running parallelly, and if there is no common runtime storage shared between the pods, you may choose to use multiple client secrets for each pod for quicker retrieval of the access token or to avoid race conditions to rotate access tokens.
Based on your implementation architecture, use case, and the level of security you want to implement, you may decide to create single or multiple client secrets.
Last updated
