Authentication
Learn how authenticate
There are three ways of authenticating depending on your needs. Start with the simplest querystring authentication to learn how the API works.
- Add your API key to the querystring with key=your_api_key
- Add your API key to the request headers with x-api-key=your_api_key
- Login the user with our one-time-password feature that retrieves a JWT token
Querystring authentication
This is the simplest way to authenticate typically used to simply share code between internal developers to try things out or to simply HACK togheter something cool but it will expose your API key directly in the URL. So use with caution. Add a querystring parameter with the name key=your_api_key and that’s all.
Example: Search for a company by name adding the API key to the url
Request header authentication
This is the most used way of authenticating especially if you are building internal integrations. In the request header add the key x-api-key=your_api_key and that’s all.
Login user and retrieve JWT token
This way of authenticating is typically used only when there are external applications where you need to access the API with the users credentials. This feature is only granted by approved applications.
The process is summarized in the flow chart below and step-by-step instructions.
1. First Step - send a one-time password
Issue a HTTP POST to login-otp with the user e164PhoneNumber or emailAddresses.
2. Second Step - validate the one-time password
A one-time password will be sent to the mobile phone number valid only for a shorter time.
3. Third step - validate the one-time password
Issue a HTTP POST to login-otp-validate with the userguid and one-time password.
- Fourth Step - how to reuse the JWT token
The JWT token can be added in the request header as Bearer.