API Authentication

Access the Graphlit Data API with a JSON Web Token (JWT).

The API uses the GraphQL query language, which supports client libraries for most programming languages.

You can use a GraphQL client library, or use our native SDKs for Python and JavaScript.

To authenticate to the Graphlit Data API, you will need a JSON Web Token, or JWT for short.

On the Project Settings page of the Graphlit Developer Portal, you will find the Environment ID, Organization ID, and JWT Secret for the Environments, which have been provisioned for each Project.

Depending on your programming language, there are different approaches to create the JWT.

Native SDK Authentication


To install the Graphlit Client, use pip:

pip install graphlit-client

Code Example:

organization_id = "YOUR_ORGANIZATION_ID"
environment_id = "YOUR_ENVIRONMENT_ID"
jwt_secret= "YOUR_JWT_SECRET"

graphlit = Graphlit(

GraphQL Client Authentication

You will need a JavaScript JWT library to create and sign tokens. In this guide, we'll use the jsonwebtoken library in Node.js for illustrative purposes. Please adapt the instructions to your chosen library.

Install the jsonwebtoken library in your Node.js project with this command:

npm install jsonwebtoken

Creating and Signing a JWT

After installing the necessary library, use the following steps to create and sign a JWT:

  • Configure the Graphlit organization and environment IDs

  • Configure the JWT secret signing key for the Graphlit environment

  • Specify the expiration date/time of the JWT

  • Create the security key

  • Create the JWT signing credentials

The HMAC SHA256 (aka HS256) signing algorithm is required for the signing credentials. More information on JWT signing can be found here.

  • Create the required Graphlit claims

  • Create the JWT and write to a string

Verifying a JWT

You can verify the JWT using the same secret used to sign it. Below is an example in Node.js using the jsonwebtoken library:

const decoded = jwt.verify(token, secret);

This will print the decoded JWT to the console. If the JWT was modified or if it has expired, jwt.verify will throw an error.

Code Sample

Here is a JavaScript code sample to start with:

const jwt = require("jsonwebtoken");

// Replace these with your own values from the Graphlit environment
const organizationId = "YOUR_ORGANIZATION_ID";
const environmentId = "YOUR_ENVIRONMENT_ID";
const secret = "YOUR_JWT_SECRET";
// Specify your role (Owner, Contributor, Reader)
const role = "YOUR_ROLE";

// Define the payload
const payload = {
  "https://graphlit.io/jwt/claims": {
    "x-graphlit-environment-id": environmentId,
    "x-graphlit-organization-id": organizationId,
    "x-graphlit-role": role,
  exp: Math.floor(Date.now() / 1000) + 60 * 60, // 1 hour from now
  iss: "graphlit",
  aud: "https://portal.graphlit.io",

// Sign the JWT
const token = jwt.sign(payload, secret);

// Use JWT to call the GraphQL API

Security Considerations

Be sure to keep your secret key private. If someone else obtains it, they can create and verify JWTs as if they were you, leading to potential security breaches.

Your secrets should always be stored as environment variables. Never hard-code them in your codebase or commit them to a repository.

Last updated