How to Set Up JWT Authentication with AutoGPT Backend: Environment Configuration and Token Generation

Configure a 32+ character JWT_VERIFY_KEY environment variable and sign tokens containing sub, role, aud="authenticated", and exp claims to authenticate with AutoGPT's Bearer-JWT protected API.

The AutoGPT backend in the Significant-Gravitas/AutoGPT repository secures its HTTP endpoints using Bearer-JWT authentication implemented in the autogpt_libs.auth package. Setting up JWT authentication requires loading cryptographic secrets from environment variables, generating tokens with mandatory payload claims, and passing them via the Authorization header on every request to protected routes.

Configure the JWT Verification Key and Algorithm

The backend validates token signatures using settings loaded from autogpt_platform/autogpt_libs/autogpt_libs/auth/config.py. The system requires two primary configuration values:

• JWT_VERIFY_KEY (or SUPABASE_JWT_SECRET): The cryptographic secret used to verify token signatures (lines 24-30)
• JWT_SIGN_ALGORITHM: The signing algorithm, defaulting to HS256 (lines 28-29)

Add these to your environment or .env file before starting the services:

JWT_VERIFY_KEY=your-super-secret-jwt-token-with-at-least-32-characters-long
JWT_SIGN_ALGORITHM=HS256

The Settings.validate method in config.py enforces a minimum security standard: if the secret contains fewer than 32 characters, the system logs a warning (lines 39-44). The backend will refuse to start if the verification key is missing entirely.

Generate Valid JWT Tokens

Required Payload Claims

According to the token parsing logic in autogpt_platform/autogpt_libs/autogpt_libs/auth/jwt_utils.py, every JWT must include these specific claims:

• sub: The unique user identifier consumed by AutoGPT
• role: Either "user" or "admin" (required for verify_user checks)
• aud: Must be "authenticated" (enforced by parse_jwt_token)
• exp: Unix timestamp (seconds) indicating token expiration

Python Token Generation Example

Use pyjwt (version 2.0+) to generate compatible tokens:

import jwt
import datetime
import os

# Load the same secret configured in the backend

secret = os.getenv("JWT_VERIFY_KEY", "your-super-secret-jwt-token-with-at-least-32-characters-long")

payload = {
    "sub": "my-user-id",
    "role": "user",
    "aud": "authenticated",
    "exp": datetime.datetime.utcnow() + datetime.timedelta(hours=2),
}

token = jwt.encode(payload, secret, algorithm=os.getenv("JWT_SIGN_ALGORITHM", "HS256"))
print(f"Bearer {token}")

Authenticate API Requests with Bearer Tokens

Authorization Header Format

AutoGPT's FastAPI dependency bearer_jwt_auth (defined in jwt_utils.py lines 13-16) expects the Authorization header using the Bearer scheme:

curl -H "Authorization: Bearer <your-jwt-here>" \
     https://api.auto-gpt.example.com/v1/agents

FastAPI Dependency Injection

Protected endpoints rely on the get_jwt_payload dependency (lines 19-45) to extract and validate the token. The dependency decodes the JWT, verifies the signature against JWT_VERIFY_KEY, and returns the payload dictionary to the route handler.

Python client example using httpx:

import httpx
import os

API_URL = "https://api.auto-gpt.example.com/v1/agents"
JWT = os.getenv("MY_JWT")

headers = {"Authorization": f"Bearer {JWT}"}

async def list_agents():
    async with httpx.AsyncClient() as client:
        resp = await client.get(API_URL, headers=headers)
        resp.raise_for_status()
        return resp.json()

Implement Role-Based Access Control

The verify_user function in jwt_utils.py (lines 68-80) enforces role-based restrictions. When a route requires administrative access (admin_only=True), the payload must contain "role": "admin". If the role check fails, the backend returns 403 Forbidden (lines 77-79).

Standard user endpoints only require the sub claim and a valid signature, while admin-only routes explicitly validate the admin role string.

Configure JWT in Docker Compose

When deploying the full platform via Docker, propagate the secret through autogpt_platform/db/docker/docker-compose.yml (or the root docker-compose.yml). All services—including PostgREST, Gotrue, and the API—read from the same JWT_VERIFY_KEY environment variable:

services:
  api:
    environment:
      - JWT_VERIFY_KEY=${JWT_VERIFY_KEY}
      - JWT_SIGN_ALGORITHM=${JWT_SIGN_ALGORITHM:-HS256}

Place the values in a .env file at the repository root (see .env.default line 33 for the template). The backend TESTING.md file also provides guidance on mocking JWTs for local development.

Summary

• Set JWT_VERIFY_KEY (or SUPABASE_JWT_SECRET) with at least 32 characters in autogpt_platform/autogpt_libs/autogpt_libs/auth/config.py via environment variables
• Use HS256 (default) or specify an alternative via JWT_SIGN_ALGORITHM
• Include mandatory claims (sub, role, aud="authenticated", exp) when generating tokens with pyjwt
• Pass tokens in the Authorization: Bearer <token> header; FastAPI extracts them via get_jwt_payload
• Set "role": "admin" in the payload to access admin-only endpoints protected by verify_user
• Configure Docker services to share the same JWT_VERIFY_KEY through compose environment variables

Frequently Asked Questions

What environment variables are required for JWT authentication in AutoGPT?

You must set JWT_VERIFY_KEY (minimum 32 characters) or SUPABASE_JWT_SECRET as a fallback. Optionally set JWT_SIGN_ALGORITHM to specify the cryptographic method (defaults to HS256). These are loaded in autogpt_platform/autogpt_libs/autogpt_libs/auth/config.py.

What algorithm does AutoGPT use for JWT verification?

The backend defaults to HS256 (HMAC with SHA-256) as defined in config.py lines 28-29. You can override this via the JWT_SIGN_ALGORITHM environment variable, but the verification logic in jwt_utils.py expects the token to be signed with whatever algorithm is configured.

How do I access admin-only endpoints?

Include "role": "admin" in your JWT payload claim. The verify_user function in jwt_utils.py (lines 68-80) checks this claim when admin_only=True is passed; otherwise, it returns a 403 Forbidden response (lines 77-79).

Can I use Supabase JWT tokens with AutoGPT?

Yes. The backend accepts Supabase-style tokens because it recognizes the SUPABASE_JWT_SECRET environment variable as an alias for JWT_VERIFY_KEY. Ensure your Supabase token includes the required sub, role, aud="authenticated", and exp claims to pass validation in jwt_utils.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}