Relay Documentation

Authentication

Learn how to authenticate requests to the Relay Management API.

Note — This page covers authentication for the Management API (creating APIs, generating keys, etc.). It does not cover how client requests authenticate through the Relay Gateway to your upstream services (which use API keys).

User Bearer Tokens

Browser requests to the Relay Management API are authenticated using a Bearer token provided in the Authorization header. The token is a JWT (JSON Web Token) issued by the authentication provider (e.g., Neon Auth).

Most management endpoints also require a workspace context to ensure you have the correct permissions (e.g., admin or owner). You can provide this context using the x-workspace-id HTTP header, or as a query parameter ?workspaceId=....

Personal Access Tokens

For programmatic access to the Management API (e.g. from CI/CD pipelines or scripts), you can generate a Personal Access Token in your workspace settings.

These tokens act as long-lived Bearer tokens and grant full administrative access to your workspace. Treat them securely. Pass them in the Authorization header just like a standard JWT token.

Example request with Personal Access Token

Copy# Authenticating with the Relay Management API curl -X GET https://relay-g0ia.onrender.com/apis \ -H "Authorization: Bearer $RELAY_TOKEN" \ -H "x-workspace-id: 1"

Unauthorized Errors

If authentication fails, the API will return a 401 Unauthorized response. The JSON body will include an error field describing the reason.

Common 401 error messages include:

Unauthorized: No token provided - The Authorization header was missing.
Unauthorized: Invalid token - The JWT signature was invalid or expired.
Unauthorized: Invalid session - The session cache lookup failed.
Unauthorized: Token missing email or sub - The token payload was malformed.

Example error response · 401 Unauthorized

Copy{ "error": "Unauthorized: No token provided" }