Skip to main content

Getting Started & Authentication - APIv1

Updated

This article explains the four-step process for first verification with Propelus: obtain credentials, request a bearer token valid for 2 hours, use the token in API calls, and refresh it regularly. Credentials must be kept secret. A sandbox environment is provided for safe testing before going live. Business users typically don’t handle these steps, as their technical teams manage tokens behind the scenes.

 

Four steps to your first verification

  1. Get your credentials. During onboarding Propelus issues your organization a client ID, a username, and a password.
  2. Request an access token. Your system sends those credentials to the token endpoint and receives a temporary bearer token in return.
  3. Make requests with the token. Each API call carries the token in its Authorization header, so Propelus knows it’s really you and what you’re allowed to see.
  4. Refresh every 2 hours. Tokens are valid for 2 hours. When one expires, request a new one and carry on — no interruption to your work.
Keep your credentials secret
Treat your client ID, username, and password like account credentials. Never paste them into emails, spreadsheets, or anything public-facing. If they’re ever exposed, contact us right away and we’ll rotate them.
 
For your technical team
The exact request and response your developers integrate. You won’t need this day to day.
Issues a Bearer token
{
 "grant_type": "password", //Required
 "username": "string",     //Required
 "password": "string",     //Required
 "client_id": "string".    //Required
}

The response is a bearer token, valid for 2 hours:

{
  "token": "string",
  "token_type": "Bearer",
  "token_format": "opaque",
  "scope": "string",
  "issued_at": 1697500046,
  "expires_at": 1697507246
}
Response field Meaning
token The bearer token to use on later requests.
token_type Always Bearer.
token_format Always opaque.
scope Reserved for future use.
issued_at When the token was issued (Unix epoch seconds).
expires_at When it expires — 2 hours after issue (Unix epoch seconds).

Send the token on every subsequent request.

 

 

Example cURL Request
# Request a token
curl --request POST \
 --url https://auth.demo.propelus.com/v1/auth/token \
 --header 'Accept: application/json' \
 --header 'Content-Type: application/json' \
 --data '{
 "grant_type": "password",
 "username": "string",
 "password": "string",
 "client_id": "string"
}''

 

 

Test safely before you go live

You’ll get a sandbox environment with test data, so your team can try requests and see real-shaped responses without touching live records. When everything looks right, you switch to the live environment.

Do business users need to do this?
Usually not. Day to day, you’ll see verification results inside your own compliance tool. Keys and tokens are handled once, behind the scenes, by your technical team.

 

Where to go next

Ready to understand what actually happens during a check? 

Read making a verification request.

Related articles