Skip to content

API Authentication

Before sending requests to the GraphQL API, an authentication process must be performed. API authentication is achieved by obtaining a JWT from our /auth endpoint by using an API key.

Need an API key?

Users can obtain an API key from the Horizon3.ai Portal.

Authenticate

Examples for obtaining an authenticated JWT are given below. Each example sends an HTTP request to the Horizon3.ai auth endpoint, which gets referenced via the environment variable H3_AUTH_URL:

export H3_AUTH_URL=https://api.horizon3ai.com/v1/auth

Before proceeding, store your API key in environment variable H3_API_KEY:

export H3_API_KEY=<your-api-key>

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"key": "'"$H3_API_KEY"'"}' \
     $H3_AUTH_URL

import os
import requests

url = os.environ["H3_AUTH_URL"]
response = requests.post(url, headers=headers, json={"key": os.environ["H3_API_KEY"]})
result = response.json() if response.status_code == 200 else None

{"token": "<your-api-token>"}

The resulting token can be used to send authenticated requests to the GraphQL API. Get started here:

  1. GraphQL Getting Started - recommended if you are new to GraphQL
  2. GraphQL API Reference - recommended if you are familiar with GraphQL

JWT expiration

Each JWT expires after 1 hour. If a given JWT has expired, the /graphql endpoint will respond with the token expiration message shown below. If this occurs, obtain a new JWT by re-authenticating with the /auth endpoint.

{"message":"The incoming token has expired"}

Status codes

HTTP status codes returned by the /auth endpoint are summarized below.

Code Title Description
200 Success Response contains the JWT.
400 Bad Request Malformed request, review the error message.
401 Unauthorized Not authenticated due to invalid API key.
5xx Internal Server Error An unexpected error was encountered.