BatchData APIs will only respond to requests made from identified users or applications. To authenticate users/applications, BatchData makes use of OAuth 2.0 Authorization.
OAuth 2.0 Authorization uses security tokens which provide trusted identities to users/applications. These tokens contain data for providing a unique identity, like a fingerprint, to the clients making API requests. This data is validated by BatchData’s API upon request.
Send this token in your header to access out APIs as follows -
HTTP Request Example
POST <API_ENDPOINT> HTTP/1.1
Content-Type: application/json
Authorization: <YOUR_TOKEN>
Host: <HOST_NAME>
Content-Length: 181
{
<REQUEST_PARAMS>
}
cURL Request Example
curl --request POST \
--url <API_ENDPOINT> \
--header 'Authorization: <YOUR_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
"requests": [
{
<REQUEST_PARAMS>
}
]
}'
BatchData offers three types of Bearer Tokens for authentication
Server Side Token- Server side tokens are used for offline or server side integration.Client Side Token- Client side tokens are used for public front-end applications (mobile apps, web pages, or desktop applications)Sandbox API Token- Sandbox tokens are used to simulate a real API request. Such requests will return mock data and will not incur any charges.
Server Tokens
Server Tokens are the preferred token for integrating with BatchData APIs.
You can create a Server Token by first logging into your account and clicking on API Tokens at the top right corner of your Dashboard page.
Select ADD NEW TOKEN from the right corner of the Server Side Token tile.
You will be brought to the page below where you can give your token a name. Select API endpoints for which you wish to use this token and click CREATE.
You will be able to see the created token in next screen below -
Once your Token is created, be sure to copy and store in a safe place as you will not get a second chance to retrieve it!
All the created tokens will be listed for you to update permissions or enable/disable them
A system generated token that you see in the list is used when you use the service from your BatchData account.
Client Tokens are created for additional security. With your Client Token you can specify the domain URLS and IP Addresses allowed to make authenticated calls with your token. Client Side Tokens are useful for client side applications at risks of code exposure and malicious attacks.
Client Side Tokens are currently only available for Address Auto-Complete end point.
To generate client side token, click on ADD NEW TOKEN from the top right corner of the Client Side Token section.
You will be brought to the pop-up bellow where you can include the name of your token, and add up to 10 domain URLs and/or IP Addresses.
Once your Token is created be sure to copy and store in a safe place as you get only one chance to retrieve it!
Sandbox API Token is used to simulate API request. They return mock data and are useful for testing and development.
To create a sandbox token, click on ADD NEW TOKEN from the top right corner of the Sandbox API Token tile.
The Sandbox API Token can be used to test all available end points. You can test the API end points from your application or any API platform.
API calls made using server side and client side tokens are chargeable. API calls made using sandbox token will not incur any cost.
You can also test the endpoints from our Stoplight API document as follows -
Go to specific API document from the left panel
Paste the token in the right panel with sample input payload
Change the input payload as per your needs
Select
Mock Serveroption from the dropdown next toSend API RequestbuttonClick
Send API Requestbutton to get the mock data in response.
Only Alphanumeric characters are allowed for Token name. Special characters such as /.!+ are not permitted.