Generating an access token

All endpoints are protected by a short-lived access token which is generated by the /v1/token endpoint. This is similar to OAuth's client credentials grant.

Once you generate the access token, send it through the Authorization header as follows:

Authorization: Bearer <access-token>

Access tokens are valid for 20 minutes and must be generated using Client ID and Secret obtained from Incognia dashboard.

Below are some examples of how to get an access token and renew it when necessary. Here is an example of how to implement an API client:

Ruby
Ruby
incognia/api.rb
require 'faraday'
require 'json'
module Incognia
class Api
include Singleton
API_HOST = 'https://api.us.incognia.com/api/'.freeze
def register_signup(installation_id:, structured_address:)
signup_endpoint = 'v2/onboarding/signups'
params = {
installation_id: installation_id,
structured_address: structured_address
}
response = Faraday.post(
"#{API_HOST}#{signup_endpoint}",
params.to_json,
headers
)
if response.status == 200
parsed_body = JSON.parse(response.body)
parsed_body['risk_assessment']
else
# Error handling
end
end
private
def headers
{
'Content-Type': 'application/json',
Authorization: "Bearer #{fresh_token}"
}
end
def fresh_token
unless @current_token&.valid?
@current_token = AccessToken.generate_access_token
end
@current_token.access_token
end
end
end

And here is an example of token refresh management:

Ruby/Rails
Ruby/Rails
incognia/access_token.rb
require 'faraday'
require 'json'
module Incognia
class AccessToken
API_HOST = 'https://api.us.incognia.com/api/'.freeze
AUTH_ENDPOINT = 'v1/token'.freeze
EARLY_EXPIRATION_IN_SECONDS = 60.freeze
class << self
def generate_access_token
headers = { 'Content-Type': 'application/x-www-form-urlencoded' }
connection = Faraday.new do |f|
f.basic_auth(ENV['INCOGNIA_API_CLIENT_ID'], ENV['INCOGNIA_API_SECRET'])
end
response = connection.post("#{API_HOST}#{AUTH_ENDPOINT}", nil, headers)
parsed_body = JSON.parse(response.body)
new(
access_token: parsed_body['access_token'],
expires_in: parsed_body['expires_in'],
)
end
end
def initialize(access_token:, expires_in:)
@created_at = Time.now
@access_token = access_token
@expires_in = expires_in.to_i
end
attr_reader :access_token
def valid?
expiration_time = Time.at(
@created_at.to_i + @expires_in - EARLY_EXPIRATION_IN_SECONDS
)
Time.now <= expiration_time
end
end
end

post
Get access token

https://api.us.incognia.com/api/v1/token
Use the client_id and client_secret to generate an API access token.This token lasts 20 minutes for security reasons. Call this endpoint every time you need a fresh access token.
Request
Response
Request
Headers
Content-type
required
string
application/x-www-form-urlencoded
Authorization
required
string
Basic Base64(client_id:client_secret)
Response
202: Accepted
Token successfully generated. Default expiration time: 20 minutes
{“access_token”: “<token>”, “expires_in”:“1200", “token_type”:“Bearer”}

Or you can simply use the following cURL command, replacing client_id and client _secret.

curl -XPOST -u '<cliend_id>:<client_secret>' -H "Content-type: application/x-www-form-urlencoded" "https://api.us.incognia.com/api/v1/token"