Relay exposes an OAuth API for AI agents and the apps they sign into. The HTTP surface lives under /relay/* on the platform API host. Hosted consent lives on relay.empyre.dev.
You integrate by registering a client, sending owners to consent, exchanging codes server-side, and refreshing tokens on a schedule. Introspect and revoke keep unattended runs fail-closed.
The sections below map each endpoint, what @empyre/relay-sdk wraps, and how Relay billing differs from a generic API gateway. For philosophy of agent identity, use the autonomous-software essay linked at the end.
Two hosts, one product
Browser flows start on the Relay product host. Token, introspect, revoke, and userinfo are POST or GET calls to the platform API.
Default API base is https://api.empyre.dev. The SDK sends JSON bodies to /relay/oauth/token, /relay/oauth/introspect, and /relay/oauth/revoke.
Consent URLs default to https://relay.empyre.dev/consent. Override with consentUrl or RELAY_AUTHORIZE_URL for staging.
Relay has been feature-frozen since 2026-07-10. Bug and security fixes only. Scoped GET /relay/oauth/userinfo shipped 2026-08-06.
OAuth endpoints under /relay/oauth/*
| Endpoint | Method | Who calls it | Purpose |
|---|---|---|---|
/relay/oauth/authorize | GET (browser redirect) | Owner browser via your app | Starts hosted consent. Returns a one-time code on redirect. S256 PKCE is mandatory. |
/relay/oauth/token | POST | Your server or worker only | Exchanges authorization codes, refreshes access, or mints agent tokens (client-credentials shape). |
/relay/oauth/introspect | POST | Your server | RFC 7662: is this access or refresh token still active? Fails closed when unsure. |
/relay/oauth/revoke | POST | Your server | RFC 7009: end a token or refresh family. Answers 200 even if the token was unknown. |
/relay/oauth/userinfo | GET | Your server with bearer access token | Returns consented profile claims. profile → name fields; email → email fields; agent subjects return sub alone. |
/relay/oauth/clients/resolve | GET | Your server | Maps a verified app domain to public client_id and display metadata. Never returns secrets. |
Authorize: consent URL, not a JSON API
Do not POST credentials to authorize. Build a URL with response_type=code, registered client_id, exact redirect_uri, scopes, high-entropy state, and PKCE challenge.
Relay refuses plain PKCE. Use S256 only. The code verifier stays on your server until token exchange.
On approval, the browser returns to your redirect with ?code= and state. Validate state, then exchange the code once.
Deny paths exist for consent rejection. Treat a missing or replayed code as invalid_grant, not a model retry.
Token POST: three grants on one path
All grants hit POST /relay/oauth/token. Bodies may be JSON or form-encoded per RFC 6749:
authorization_code
Fields: code, code_verifier, redirect_uri, client_id, optional client_secret. Response: access_token, token_type, expires_in, scope, optional rotated refresh_token.
refresh_token
Fields: refresh_token, client_id, optional client_secret. Each success rotates refresh. Replaying a spent refresh revokes the family.
Agent client-credentials (Relay Identity)
Fields: grant_type client_credentials shape with agent_id, agent_secret, audience or client_id, optional scope. May return pending_approval until the owner approves.
Introspect, revoke, and userinfo shapes (high level)
Server-side only. Never forward these calls from agent prompts:
Introspect body
token plus client auth (client_id, client_secret, or project api_key). Active tokens return active, scope, sub, client_id, optional subject_type user or agent.
Revoke body
token plus the same client auth. Use before offboarding an agent or after detecting refresh replay.
Userinfo headers
Authorization: Bearer <access_token>. Missing, expired, or revoked tokens get 401 with no partial claims.
What @empyre/relay-sdk wraps (1.0.0)
| SDK method | HTTP target | Notes |
|---|---|---|
authorizeUrl() | Builds query on consent URL | Requires clientId. Validates state length and S256 challenge format. |
exchangeCode() | POST /relay/oauth/token | Authorization code grant with PKCE verifier. |
refresh() | POST /relay/oauth/token | Refresh grant with rotation handled server-side. |
authenticateAgent() | POST /relay/oauth/token | Resolves audience domain via /relay/oauth/clients/resolve when clientId omitted. |
verifyToken() | POST /relay/oauth/introspect | CLI: npx @empyre/relay-sdk verify. |
revokeToken() | POST /relay/oauth/revoke | CLI: npx @empyre/relay-sdk revoke. |
| (no helper) | GET /relay/oauth/userinfo | Call with fetch and bearer header today. Scope-gated claims per OpenAPI. |
MCP and CLI on the same contract
Relay's MCP server lives at https://relay.empyre.dev/mcp. It exposes OAuth tools for agents that connect through MCP hosts, not a separate HTTP API surface.
The npm package ships a CLI for authorize URLs, verify, revoke, and agent login. Those commands hit the same /relay/oauth/* paths the SDK uses.
For install intent and MCP paste URLs, read the Relay plugin article. This page is the HTTP map.
Auth requests vs downstream API traffic
Relay bills in auth requests, not every HTTP call your product makes afterward.
An auth request counts each OAuth token issuance and refresh your registered clients perform. Gmail or GitHub traffic after you hold an access token is yours, not Relay metered per call.
Self-serve tiers on relay.empyre.dev/pricing on 2026-09-30: Relay Platform free tier includes 10,000 requests per month; Developer is $49 per month for 500,000 requests; Team is $299 per month for 5,000,000 requests. Enterprise is invoiced separately. Relay Identity has its own agent-seat tiers on the same page.
Relay subscriptions are separate from Empyre company-builder plans. Card checkout uses Stripe; Relay state lives in Relay tables.
Not an HTTP API gateway
A generic API gateway proxies arbitrary URLs with rate limits and static credentials. Relay does not replace your app's REST routes.
Relay is an OAuth broker for delegated login and agent identity. It issues and rotates bearer tokens. Your app still calls third-party APIs with those tokens.
For the gateway pattern and when you need a broker instead, read API relay for AI agents. For grant-level detail at the token endpoint, read Agent OAuth token exchange.
Empyre ships Relay alongside Vault and the company operator on empyre.dev. Wiring Relay does not publish your product; it secures how agents authenticate to it.
Minimal server-side wiring (SDK 1.0.0)
Exchange stays on the server. The agent runtime receives only short-lived access:
import { RelayClient, createOAuthState, createPkcePair } from "@empyre/relay-sdk";
const relay = new RelayClient({
clientId: process.env.RELAY_CLIENT_ID,
clientSecret: process.env.RELAY_CLIENT_SECRET,
});
const { verifier, challenge } = await createPkcePair();
const state = createOAuthState();
// Send the owner here once:
const consent = relay.authorizeUrl({
redirectUri: "https://yourapp.com/callback",
state,
codeChallenge: challenge,
scopes: ["openid", "profile"],
});
// On callback, server route only:
const tokens = await relay.exchangeCode(req.query.code, verifier, "https://yourapp.com/callback");
const info = await fetch("https://api.empyre.dev/relay/oauth/userinfo", {
headers: { Authorization: `Bearer ${tokens.access_token}` },
}).then((r) => r.json());
const active = await relay.verifyToken(tokens.access_token);
Common questions
What npm package is the Relay API client?
@empyre/relay-sdk version 1.0.0 on registry.npmjs.org, verified 2026-09-30. Scope is @empyre, not @empyre/relay.
Where is the OpenAPI description?
Public paths including /relay/oauth/* are in the Empyre public OpenAPI document served from the platform API docs surface. Token, introspect, revoke, and userinfo match production behavior.
Can my agent call /relay/oauth/token directly?
No. Agents must not hold client secrets, refresh tokens, or authorization codes. Your broker or API layer performs token calls.
How is this different from the API relay article?
That page compares OAuth brokers to HTTP gateways conceptually. This page lists Relay's concrete endpoints and SDK mapping.
How is this different from the Relay plugin article?
That page answers SDK and MCP install search intent. This page is the ready-to-buy HTTP reference for the same product.
Does Relay proxy my Gmail requests?
No. Relay issues tokens. Your server attaches Authorization when calling upstream APIs.
Try Starter free for 3 days
Describe a business in plain words and watch eight AI agents build and deploy it. Starter is free for the first 3 days; a card starts the trial.
Related
Last updated 2026-11-21. Competitor descriptions reflect each product's publicly documented capabilities at that date; they change often, so check the source before relying on a detail.