Authentication
The Tiller Verifications API uses token-based authentication via the OAuth 2.0 protocol. To ensure secure communication and protect sensitive data, every request to the API requires a valid access token in the Authorization
header.
Prerequisities
To use the Tiller Verifications API, you'll need some credentials. This is essential for authenticating your requests and ensuring secure access to the system. Here’s how to get started:
Contact your Tiller account manager to request your API credentials. -
Safeguard your credentials; it is required for authorization. Treat it like a password—never share it or expose it publicly.
Obtain an Access Token
To authenticate your requests, you need to retrieve an access token by sending a POST
request to the authentication /connect/token
endpoint. The request should include the following form data:
grant_type
Yes
Specifies the OAuth 2.0 grant type. Use client_credentials
.
client_id
Yes
Your client unique identifier provided by Tiller.
client_secret
Yes
Your secret key provided by Tiller.
scope
Yes
Use VerificationsAPI
as the scope.
Obtain an authentication token using client credentials.
client_credentials
{{scope}}
{{client_id}}
{{client_secret}}
POST /connect/token HTTP/1.1
Host: verifications-auth.tiller-verify.com
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 119
"grant_type='client_credentials'&scope='{{scope}}'&client_id='{{client_id}}'&client_secret='{{client_secret}}'"
{
"access_token": "text",
"token_type": "text",
"expires_in": 1
}
Example request
curl --location 'https://verify-auth.tiller-verify.com/connect/token' \
--header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=VerificationsAPI' \
--data-urlencode 'client_id=CLIENT_ID' \
--data-urlencode 'client_secret=CLIENT_SECRET'
Example response
{
"access_token": "eyJhbGciOiJS...",
"expires_in": 600,
"token_type": "Bearer",
"scope": "VerificationsAPI"
}
To use the access token with the Verifications service, include it in the Authorization
header of your HTTP requests.
Best Practices for Using Access Tokens
Token Renewal: Monitor the token’s expiry and implement logic to request a new one before making further API calls.
Secure Transmission: Always use HTTPS to prevent interception of the access token during transmission.
Scope Management: Use minimal scopes necessary for each request to enhance security.
By including the access token in your requests, you gain secure and authenticated access to the Verifications service, protecting sensitive information.
Last updated