Skip to main content
Version: v5

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 the Client ID and Secret obtained from Incognia dashboard.

To generate the Client ID and Secret, go to the Integrations page and click on the 'APIs' tab. Then, click on 'Create API credentials' and give a name to your credentials:

Click on 'Save and close' and you will be able to use the token endpoint below.

When fetching the token by calling the endpoint below, make sure that the client id and secret are encoded in base64.

Getting the access token#


Uses the client_id and client_secret to generate an API token. It's important to realize that this token lasts 20 minutes, and you'll have to call this route again when it is expired.


AuthorizationstringRequiredBasic Base64(client_id:client_secret)

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

Code sample#

An example of how to get an access token and renew it when necessary is as follows:

# incognia/api.rbrequire 'faraday'require 'json'
module Incognia  class Api    include Singleton
    API_HOST = ''.freeze
    def register_signup(installation_id:, structured_address:)      signup_endpoint = 'v2/onboarding/signups'      params = {        installation_id: installation_id,        structured_address: structured_address      }
      response =        "#{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
    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  endend
# incognia/access_token.rbrequire 'faraday'require 'json'
module Incognia  class AccessToken    API_HOST = ''.freeze    AUTH_ENDPOINT = 'v1/token'.freeze
    class << self      def generate_access_token        headers = { 'Content-Type': 'application/x-www-form-urlencoded' }
        connection = do |f|          f.basic_auth(ENV['INCOGNIA_API_CLIENT_ID'], ENV['INCOGNIA_API_SECRET'])        end        response ="#{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 =      @access_token = access_token      @expires_in = expires_in.to_i    end
    attr_reader :access_token
    def valid?      expiration_time = + @expires_in) <= expiration_time    end  endend