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

  • [email protected].

• 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:

Parameter	Required	Description
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.

Authentication token

post

Obtain an authentication token using client credentials.

Body

application/x-www-form-urlencoded

grant_typestringRequiredDefault: client_credentials

scopestringRequiredDefault: {{scope}}

client_idstringRequiredDefault: {{client_id}}

client_secretstringRequiredDefault: {{client_secret}}

Responses

200

Successful response

application/json

access_tokenstringOptional

token_typestringOptional

expires_inintegerOptional

default

Unexpected error

application/json

post

/token

HTTPcURLJavaScriptPython

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

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'

Python Requests

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.