Tokens

Introduction

This document details generating access tokens that can be used by your web clients to make secure, direct calls to Factual’s APIs. Using tokens enables you to avoid proxying API calls through your own servers and is a required piece of implementing an embeddable UI workflow.

Requirements

The basic requirements to implement tokens to access Factual are:

  • A server in your control that can authenticate your clients against your own user DB
  • A Factual API key
  • The ability for your server to make an outbound API call to Factual
  • The ability for your server to forward the results of an API call from Factual to your clients

The diagram below details the basic authentication flow:

As shown in the diagram above, the basic steps are:

  1. Your user attempts to login from one of your clients by sending login credentials to your server.
  2. Assuming the user has acceptable credentials, your server will either:
  • Return the most recent Factual authentication token it has for the user (assuming that it hasn’t passed its expiration date).1
  • Request a new token from Factual on behalf of that user.2
  1. In the event a token was requested, Factual will return the token to your server.
  2. Your server in turn will return the access token to the client.
  3. Your client will use the token to make a request to Factual.
  4. Factual will determine if the token is valid, and what permissions it should have.
  5. As appropriate, Factual will return data to the client.

📘

Note: Until your client’s Factual token has expired, your client does not need to re-request tokens to make calls to Factual.

1There is no harm in asking for a token redundantly. Factual will consistently return the same token is for that user.

2If this is the first time the user has requested access to Factual, all necessary configuration on Factual’s side will be performed immediately, in order to respond to your server’s request in a timely manner. I.e., each user’s Factual credentials are generated quickly but lazily.

Getting an API Key

If you haven’t already, contact Factual to register an account. Once you’ve done that (or logged into Factual), go to the Factual API key manager at https://www.factual.com/keys.

  1. Within the key manager, you’ll be generating a Server App key:
  1. After you generate your Server App key, hit modify.
  2. Click the Security and Permissions tab.
  3. Enter the IP address of your server. This helps prevent use of your API key to generate tokens from unauthorized domains, if it were to be compromised.
  4. Hit save.
  5. Your API key is listed as OAuth Key. For this use case, you will not require the OAuth Secret.

Getting Tokens

Tokens are generated using an https request to Factual’s V4 API. Authentication of your token API call is performed simply by supplying your API key to the KEY parameter (all CAPS) to the /token/user endpoint. Along with your API key, the following parameters are required (unless you provide a user Id, as detailed later):

  • email (User email address.)
  • first_name (first name of user. must not be blank or all white space.)
  • last_name (last name of user. must not be blank or all white space.)

Token API Request

The basic syntax for getting a token is to make a GET request as follows:

https://api.factual.com/token/user?email=email_address&first_name=first_name&last_name=last_name&KEY=api_key
  • As per any http GET request parameter, the email address and first/last names must be URL-encoded.
  • The request must be transmitted securely through https.

Refresh Token API Request

Once you have received a successful token response containing a user id, you should request future tokens for that user simply using the user id:

https://api.factual.com/token/user/user_id?KEY=api_key

Token API Response

Responses to the Factual API contain a JSON object in the response body, in addition to metadata in the http headers and the http status code. The standard http response body will contain data conforming to the JSend convention, augmented with a few other attributes:

  • status (success, fail, error)
  • data (for success_/_fail)
  • message (for error)
  • version (API version)

Standard Response

An http 200 response will be accompanied with JSON, similar to the following, containing the user’s userId, token and the expiration date of the token:

{
  "version":4,
  "status":"success",
  "data":{
    "uid":"fbd96e3a-1d7d-4a93-b201-020e53e65417",
    "token":"XTH4sYzIjP5cG6RzqSoi",
    "expiration":1443650290
  }
}

You should forward both the token and expiration date to your clients. The expiration date will be in epoch time, in seconds.

Exceptional Paths

HTTP Response Code

Message

Explanation

400

unknown parameter ‘parameter_name’

You have entered a parameter that the API does not recognize.

400

parameter ‘parameter_name’ should not be used alongside a user id.

You have provided both a user id (in the URL) as well as user identifying information such as email, first_name, or last_name. You should only be providing the user Id if you have it.

400

missing required parameter ‘parameter_name’

You have not provided a user id and any of the email, first_name or last_name parameters is either missing or blank.

400

invalid email address

The email address you provided is invalid.

401

invalid API key

Your API key is not valid. This is most likely because you’ve either regenerated your API key (invalidating the existing one), or because you’ve made a copy/paste mistake.

403

throttled

You’ve made too many API calls over the allotted period of time.

404

resource not found

There is a typo somewhere in the request URL.

404

user not found

The user id provided in the URL is invalid.

Using Tokens

Once your client has a token and expiration date, it can make API requests directly to Factual. In order to make requests to Factual:

  1. Ensure that the expiration date for the token has not passed. If it has, your client-side code should be prepared to ask your server for a new token, which it will have to fetch from Factual.
  2. Insert the valid token into the Authorization header as an OAuth 2.0 Bearer token.
    For example, if the token is XTH4sYzIjP5cG6RzqSoi, the header would look like:
GET /geopulse/designs/ HTTP/1.1
Host: api.factual.com
Authorization: Bearer XTH4sYzIjP5cG6RzqSoi

Refreshing Tokens

If the token has expired, your server simply needs to make a new request to the token API with the appropriate user id. Factual will return a new token.