Relay API

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/*`

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:

Introspect, revoke, and userinfo shapes (high level)

Server-side only. Never forward these calls from agent prompts:

What `@empyre/relay-sdk` wraps (1.0.0)

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 deploy 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

Related

Last updated 2026-09-30. Competitor descriptions reflect each product's publicly documented capabilities at that date; they change often, so check the source before relying on a detail.