Authentication

Before you can access the PredictHQ API and all its magic, you need to prove you are who you say you are. The PredictHQ API uses the OAuth 2.0 standard for authentication.

After you sign up you can create an API client and token with Control Center. See how to create an API client and token. Once you've created a token you can use that token with the API.

Creating a token via the API

You can also create an API token using the API. For most users, it's easier to use our Control Center web app to create a token but for advanced users, if you want to create a token programmatically you can use this approach.

To create a token with the API all you need to do is to request an Access Token that will grant your API Client access to the various tools and resources available via the PredictHQ API.

All requests to the OAuth 2.0 endpoint must be given your credentials in the form of Basic authentication. To comply with the HTTP requirements, your Client ID and Secret should be encoded in base 64.

This can easily be done via this command line:

raw
echo -n "$CLIENT_ID:$CLIENT_SECRET" | base64 -w 1000

then by adding a header to your HTTP requests:

raw
Authorization: Basic base64($CLIENT_ID:$CLIENT_SECRET)

URL

raw
https://auth.predicthq.com/token

Because it is based on a standard, the URL to the OAuth2.0 endpoint does not require a version number.

Requesting an Access Token

When requesting an Access Token, use the client_credentials grant type, then request the scope or scopes you wish to have access to. These scopes can be any or all of the following, separated by a space:

Scope Description
account Grants access to the account endpoint.
events Grants access to the events endpoint.
places Grants access to the places endpoint.
broadcasts Grants access to the broadcasts endpoint.

Access Token Lifetime

Please note that Access Tokens requested via the client_credentials grant type never expire.

Action

raw
POST /token/

Example

curlpythonraw
curl -X POST https://auth.predicthq.com/token \
     -u "$CLIENT_ID:$CLIENT_SECRET" \
     -d "grant_type=client_credentials" \
     -d "scope=account events places"
raw
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
    "access_token": "$ACCESS_TOKEN",
    "token_type": "Bearer",
    "scope": "account events places"
}

Accessing Protected Resources

Before you can harness the full power of PredictHQ's event intelligence, you need to authenticate your requests using your Access Token.

Once again, to make it easy for you, PredictHQ follows the standard as outlined in the OAuth 2.0 Bearer Token reference.

Example

curlpythonraw
curl -X GET https://api.predicthq.com/v1/events/ \
     -H "Authorization: Bearer $ACCESS_TOKEN"