Overview

Authentication

All TextReveal® API endpoints requests are authenticated using the JWT token. It requires you to provide a username and a password to our OAuth token endpoint and receive the token inside the response. Used this token for each API request.

The username is your API Key and the password is your API Secret Key - you can get them from our support. Both keys are generated automatically when your account is created.

TextReveal® API service uses OAuth 2.0, an industry-standard protocol for authorization.

Communicating with an authenticated endpoint is a two steps process:

Acquire a JWT access token from the OAuth token endpoint
Call a TextReveal® API endpoint with the JWT access token.

How to acquire a JWT Access Token

For security purpose, your JWT Access Token is valid for 24 hours.

You can create a cron job to retrieve a new token each 24 hours.
You can use AWS secret manager with lambda and event bridge for the rotation.

In order to acquire a JWT Access Token, you should follow the following steps:

Make an HTTP POST request to the endpoint https://login.textreveal.com/oauth/token

Include the header: Content-type: application/json
Include the body:

{
  "grant_type": "password",
  "username": "<TR_USERNAME>",
  "password": "<TR_PASSWORD>",
  "audience": "https://api.textreveal.com/",
  "client_id": "2vlZbytm6YvS48bl0lH3Dcjxq87iXX4w"
}

Example using curl

# Example:
curl --request POST \
  --url https://login.textreveal.com/oauth/token \
  --header 'Content-Type: application/json' \
  --data '{
    "grant_type": "password",
	"username": "<TR_USERNAME>",
	"password": "<TR_PASSWORD>",
	"audience": "https://api.textreveal.com/",
	"client_id": "2vlZbytm6YvS48bl0lH3Dcjxq87iXX4w"
}'
 
# Response:
{
	"access_token": "eyJhbGci[...]k6Kf_wQ",
	"expires_in": 86400,
	"token_type": "Bearer"
}

Then extract the access_token from the response

Example using python OAuthLib

Install the required python modules

Connecting to the API requires some modules that are not bundled directly with Python.
Assuming Python is already installed on your system, you can install the dependencies from a terminal:

pip install requests requests-oauthlib

Create a configuration file

We recommend using environment variables for your credentials.

config/auth.json

{
  "api": {
    "_audience": "https://api.textreveal.com/",
    "_client_id": "2vlZbytm6YvS48bl0lH3Dcjxq87iXX4w",
    "_token_url": "https://login.textreveal.com/oauth/token",
    "host": "https://api.textreveal.com"
  },
  "credentials": {
    "username": "Your username",
    "password": "Your password"
  }
}

Create a script to acquire a JWT Access Token

auth.py

import json
 
from oauthlib.oauth2 import LegacyApplicationClient
from requests_oauthlib import OAuth2Session
 
 
def read_auth_config():
    with open("./config/auth.json") as fp:
        return json.loads(fp.read())
 
 
def get_token(config):
    api = config["api"]
    credentials = config["credentials"]
    session = OAuth2Session(client=LegacyApplicationClient(client_id=api["_client_id"]))
    return session.fetch_token(
        username=credentials["username"],
        password=credentials["password"],
        token_url=api["_token_url"],
        audience=api["_audience"],
        client_id=api["_client_id"],
        include_client_id=True,
    )["access_token"]

How to use a JWT Access Token

Include the following header in all calls to TextReveal® API endpoint.

Authorization: Bearer YOUR_TOKEN

Example using curl

# Example:
curl --request POST \
  --url https://api.textreveal.com/api/2.0/kg/candidates \
  --header 'Authorization: Bearer eyJhbGci[...]k6Kf_wQ' \
  --header 'Content-Type: application/json' \
  --data '{
  "keyword_of_interest": "Apple",
  "max_results": 2,
  "source": "corporate_kg"
}'
 
# Response:
[
  {
    "itemDescription": "Bike Rental",
    "item_id": "fancy-apple",
    "label": "Fancy Apple",
    "uuid": "1df910cb-8fc9-495e-8798-9dc6f5120bf2"
  },
  {
    "itemDescription": "Apple Patent Law Firm provides free consultations on applications, registrations, disputes, and license agreements.",
    "item_id": "apple-patent-law-firm",
    "label": "Apple Patent Law Firm",
    "uuid": "1785a396-0cc9-476e-9c2f-b49fad6a773c"
  }
]

Example using python requests

import requests
from auth import read_auth_config, get_token
 
token = get_token(read_auth_config())
 
payload = {
    "keyword_of_interest": "Apple",
    "max_results": 2,
    "source": "corporate_kg"
}
response = requests.post(
    "https://api.textreveal.com/api/2.0/kg/candidates",
    headers={"Authorization": f"Bearer {token}"},
    json=payload
)
print(response.json())