API Authentication

🔑 Authentication 10 min read Updated June 2026

Every request to the Gridlock API must be authenticated. There are two supported methods: JWT bearer tokens and API keys. Both use the same Authorization HTTP header with the Bearer scheme, but they serve different use cases and have different security characteristics.

Understanding which method to use — and how to handle it securely — is the most important step before building on the API. This guide covers both methods in detail, including how to obtain credentials, code examples, scope definitions, and security best practices.

Which Method Should You Use?

JWT Token Authentication

A JWT (JSON Web Token) is issued when a user successfully logs in. Gridlock uses JWTs for all authenticated dashboard sessions. If you are building a web application that authenticates users through the Gridlock login flow, JWTs are the correct choice.

Obtaining a Token

Post the user's credentials to the login endpoint. On success, the response includes the JWT and its expiry timestamp. The login endpoint is rate limited to 10 requests per minute per IP to prevent brute-force attacks.

POST https://lockthegrid.com/api/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "your_password_here"
}

Successful response:

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoidXNyX2Ex...",
  "expires_at": "2026-06-08T14:30:00Z",
  "user": {
    "id": "usr_a1b2c3d4",
    "email": "[email protected]",
    "org": "Premier Networx",
    "role": "admin"
  }
}

Using the Token

Pass the JWT in the Authorization header on every subsequent request using the Bearer scheme.

# curl example
curl -s \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  https://lockthegrid.com/api/user/profile

// JavaScript fetch example
const token = getStoredToken(); // retrieve from secure storage

const res = await fetch('https://lockthegrid.com/api/threats', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});

if (res.status === 401) {
  // Token expired or invalidated — redirect to login
  redirectToLogin();
  return;
}

const data = await res.json();

Token Expiry

JWT tokens expire 7 days after issuance. After expiry, the API returns 401 Unauthorized with the message "Token expired. Please log in again." Your application should detect this response and redirect the user back to the login flow to obtain a fresh token. Do not automatically retry the original request with a new login — always prompt the user for their credentials.

Token Invalidation via token_version

Every Gridlock user account carries a token_version counter. When any of the following events occur, the counter is incremented and all previously issued JWTs become immediately invalid — even if they have not yet reached their 7-day expiry:

• The user changes their password.
• The user triggers "Log Out All Sessions" from dashboard Account Settings.
• An admin revokes the user's active sessions from the team management panel.

This is an intentional security mechanism. If an account is suspected to be compromised, changing the password immediately invalidates every active session across every device and API client using JWTs for that account.

API Key Authentication

API keys are the preferred authentication method for any code running unattended: server-side integrations, cron jobs, CI/CD pipelines, webhook processors, and third-party automations. Unlike JWT tokens, API keys are not tied to a user session — they authenticate the organization's account directly and remain valid until they expire or are revoked.

API Key Format

All Gridlock API keys use the prefix gl_live_ followed by a 32-character random alphanumeric string. The prefix serves two purposes: it makes keys instantly recognizable in code review, and it allows automated secret scanning tools to detect accidentally committed keys.

gl_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Generating an API Key

1. Log in to lockthegrid.com/dashboard.
2. Navigate to Settings → API Keys.
3. Click Generate New Key.
4. Enter a descriptive name identifying this specific integration or consumer (e.g., "GitHub Actions deployment", "Zapier automation", "Internal reporting script").
5. Select the required permission scope (see Scopes below — choose the minimum necessary).
6. Optionally configure an expiry date. For long-running integrations, 90-day rotating keys are recommended.
7. Click Create Key and copy the value immediately. It will not be shown again.

Using an API Key

Pass the key in the Authorization header using the Bearer scheme — the same pattern as JWT tokens. The API automatically distinguishes between a JWT and an API key by the gl_live_ prefix.

# curl example — key from environment variable
curl -s \
  -H "Authorization: Bearer $GRIDLOCK_API_KEY" \
  -H "Content-Type: application/json" \
  https://lockthegrid.com/api/threats/summary

// Node.js example — key from environment variable
const API_KEY = process.env.GRIDLOCK_API_KEY; // never hardcode

async function runThreatResearch(domain) {
  const res = await fetch('https://lockthegrid.com/api/agents/run', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      agent: 'threat-researcher',
      target: domain,
      options: { include_cve: true }
    })
  });

  if (res.status === 403) {
    throw new Error('API key lacks write scope. Regenerate with write permissions.');
  }

  if (!res.ok) {
    const err = await res.json();
    throw new Error(err.error);
  }

  return res.json();
}

API Key Scopes

Every API key is assigned a scope that restricts what actions it can take. Follow the principle of least privilege: request only the scope your integration actually needs. Granting admin scope to a routine reporting script is unnecessary and dangerous.

Scope	What It Allows	Use When
read	All GET requests. Can retrieve any data but cannot create, modify, or delete anything.	Read-only dashboards, reporting tools, monitoring integrations that pull data from Gridlock.
write	All read permissions plus the ability to create and update resources: trigger agent runs, create tickets, update settings, submit data.	Automation scripts that trigger agent runs, integrations that write records to Gridlock from external systems.
admin	All write permissions plus account management: invite and remove users, change billing, revoke API keys, modify organization settings.	Internal account provisioning workflows and admin tooling only. Never use for routine automation.

Rate Limits by Authentication Method

Authentication endpoints are rate limited more strictly than general API endpoints to prevent credential brute-forcing. All limits are applied per IP address.

Endpoint or Context	Limit	Window
POST /api/auth/login	10 attempts	per 60 seconds, per IP
POST /api/auth/register	5 attempts	per 60 seconds, per IP
POST /api/auth/reset-password	5 attempts	per 60 seconds, per IP
All other endpoints (JWT auth)	100 requests	per minute, per IP
All other endpoints (API key auth)	100 requests	per minute, per account

Authentication Error Responses

Authentication failures return either 401 Unauthorized or 403 Forbidden. The error field provides a specific, human-readable message. These messages are intentionally safe to surface in developer tooling — they never leak stack traces, database details, or internal service names.

HTTP Status	Error Message	Root Cause
401	No authorization token provided	The Authorization header is absent from the request.
401	Invalid token format	Header is present but not structured as Bearer <value>.
401	Token expired. Please log in again.	JWT has passed its 7-day expiry window.
401	Token invalidated. Please log in again.	User changed password or revoked sessions; token_version mismatch.
401	Invalid API key	Key does not exist or has been revoked.
401	API key expired	Key exists but has passed its configured expiry date.
403	Insufficient permissions. Required scope: write	The key's scope does not permit the requested action.
401	Invalid email or password	Login attempt failed — no matching account for the supplied credentials.

Security Best Practices

This is a cybersecurity product. Authentication security must be impeccable. Follow these practices in every integration you build on the Gridlock API.

For JWT Tokens

• Store tokens in HttpOnly cookies in production — never in localStorage or sessionStorage.
• Never log full token strings in application logs, error trackers, or analytics pipelines.
• Implement proactive refresh: schedule re-authentication before the 7-day expiry rather than waiting for a 401 to interrupt a user action.
• If a user reports suspicious account activity, force-invalidate all sessions immediately using "Log Out All Sessions" in Account Settings.
• Set the Secure and SameSite=Strict cookie attributes alongside HttpOnly to prevent cross-origin cookie exposure.

For API Keys

• Always load keys from environment variables or a secrets manager at runtime. Never hardcode them in source files, configuration files committed to version control, or Docker images.
• Scope every key to the minimum permissions required. A reporting integration needs read only — do not give it write "just in case."
• Create one API key per integration consumer. If three different scripts use the API, generate three separate keys. This lets you revoke a single compromised key without disrupting the others.
• Set expiry dates on all keys used in production. 90-day rolling rotation is a reasonable baseline.
• Audit active keys regularly from Settings → API Keys. Revoke any key that has not been used in 30 days or belongs to a decommissioned integration.

Complete Login Flow (JavaScript)

// auth.js — complete JWT login and authenticated request pattern

const BASE_URL = 'https://lockthegrid.com/api';

async function login(email, password) {
  const res = await fetch(`${BASE_URL}/auth/login`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, password })
  });

  if (!res.ok) {
    const { error } = await res.json();
    throw new Error(error);
  }

  const { token, expires_at } = await res.json();

  // In production: set via HttpOnly cookie from server-side
  // In this example: sessionStorage (acceptable for short-lived demos only)
  sessionStorage.setItem('gl_token', token);
  sessionStorage.setItem('gl_token_expires', expires_at);

  return token;
}

function getToken() {
  const token = sessionStorage.getItem('gl_token');
  const expires = sessionStorage.getItem('gl_token_expires');

  if (!token || !expires) return null;
  if (new Date(expires) <= new Date()) {
    sessionStorage.removeItem('gl_token');
    return null; // expired — caller should re-authenticate
  }

  return token;
}

async function apiRequest(path, options = {}) {
  const token = getToken();
  if (!token) throw new Error('Not authenticated');

  const res = await fetch(`${BASE_URL}${path}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
      ...(options.headers || {})
    }
  });

  if (res.status === 401) {
    sessionStorage.removeItem('gl_token');
    throw new Error('Session expired. Please log in again.');
  }

  if (!res.ok) {
    const { error } = await res.json();
    throw new Error(error);
  }

  return res.json();
}

Related Pages