This page describes how authentication and authorization is implemented in the Live Data API.

Authentication

The Live Data APIs support two forms of authentication depending on the use case/endpoint:

All API calls require authentication in the form of an access token, which can be obtained using a username/password or service account credentials via the OAuth2 token endpoint.

OAuth Service Accounts and Access Tokens

Live Data uses the OAuth2 Client Credentials flow for authenticating service accounts. Create a Service Account using the UI by selecting the Teams menu on the left and the Service Accounts tab. When creating a service account, you will be provided the client secret -- this is the only time you can obtain the secret.

To authenticate using these credentials, call the Create a new session endpoint with grantType=clientCredentials and the clientId and clientSecret params populated by the service account ID and secret. This will return an access token which can be used to authenticate further calls.

Request

curl -X 'POST' \
  'https://gotlivedata.io/api/identity/v1/session' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "grantType": "clientCredentials",
  "clientId": "<your service account/client id>",
  "clientSecret": "<your client secret>"
}'

Response

{"accessToken": "eyJ0eXAiOiJKV1Qi.eyJ0eXAiOiJKV1Qi.4K20wYgWlrQ9y58-nBJU8", "expiresAt": "2021-11-19T23:36:09.092720"}

Obtaining an Access Token Using Username/Password

To obtain an access token using user credentials, call the Create a new session endpoint using your username and password.

curl -X POST https://gotlivedata.io/api/identity/v1/session \
  -d "username=<username>&password=<password>"

A successful response will be a 200 and include an access_token field in the body, along with the expiration time. Access tokens expire 1 hour after creation.

Using the access token

Use the accessToken provided in the response in any additional calls to any API. Place the token in a header called Authorization prefixed with Bearer, like below:

curl --request POST \
     --url https://gotlivedata.io/api/people/v1/o_123abc/find \
     --header 'accept: application/json' \
     --header 'authorization: Bearer eyJ0eXAiOiJKV1Qi.eyJ0eXAiOiJKV1Qi.4K20wYgWlrQ9y58-nBJU8' \
     --header 'content-type: application/json' \
     --data '
{
  "matches": [
    {
      "fields": [
        {
          "field_name": "email_address",
          "search_term": "[email protected]"
        }
      ]
    }
  ]
}
'

API Keys

Create an API Key by navigating to the Team Section in the UI and the API Keys tab. To create a new key, click the Create API Key button. Provide a name and description to help identify what and where this key will be used. Once the key has been created it will be automatically copied to your clipboard for use.

To use an API Key, place it in an http header called Authorization with the prefix Bearer, i.e. Authorization: Bearer ldtkey_12345

Authorization

All API calls require a defined 'role', which is specified in the API documentation. The user or service account making the API call must have the specified role on the organization for the API call to succeed.

Sample Python Auth Code using Service Accounts

The code below demonstrates how you might incorporate LDT auth into a Python application.

LiveDataServiceAccount Class

import requests
import time
import calendar
from datetime import datetime, timezone

LOGIN_URL = "https://gotlivedata.io/api/identity/v1/session"


class LiveDataServiceAccount:
    def __init__(self, client_id: str, client_secret: str) -> None:
        self.client_id = client_id
        self.client_secret = client_secret
        self._access_token = None
        self._expires_at = None
        self._is_logging_in = False

    def _active(self):
        if not self._access_token:
            return False

        if not self._expires_at:
            return False

        now = time.time()
        will_expire_soon = self._expires_at - now < 25

        if will_expire_soon:
            return False

        return True

    def access_token(self) -> str:
        if self._is_logging_in:
            for _ in range(25):
                time.sleep(0.5)

                if not self._is_logging_in:
                    break

        if not self._active():
            self.login()

        return self._access_token

    def login(self) -> str:
        self._is_logging_in = True

        payload = {
            "clientId": self.client_id,
            "clientSecret": self.client_secret,
            "grantType": "clientCredentials"
        }

        resp = requests.post(url=LOGIN_URL, json=payload)
        if resp.status_code != 200:
            raise Exception("Login failed")

        body = resp.json()

        self._access_token = body.get("accessToken")
        self._expires_at = int(
            calendar.timegm(
                time.strptime(body.get("expiresAt"), "%Y-%m-%dT%H:%M:%S.%f")))

        self._is_logging_in = False

Usage

The class logs in and tracks when the token will expire, always keeping it active. Just call account.access_token() to have a valid token.

We new up a LD service account in the entrypoint and pass it to the run function.

account = LiveDataServiceAccount(
    client_id="",
    client_secret=""
)

api = DwhApi(livedata_service_account=account)

The below is an example of a class you might construct that targets a specific Live Data API and incorporates the LiveDataServiceAccount class for authentication.

class DwhApi:
    def __init__(self, livedata_service_account: LiveDataServiceAccount) -> None:
        self.livedata_service_account = livedata_service_account

    def get_company(self, company_lookup: str):
        url = f"{BASE_URL}/companies/{company_lookup}"
        headers = {
            "Authorization": f"Bearer {self.livedata_service_account.access_token()}"}
        response = requests.get(url, headers=headers)

        if response.status_code == 200:
            return response.json()

        raise Exception(f"Error: {response.status_code} - {response.text}")