Building an OAuth client for Resend

Resend implements OAuth 2.0 and 2.1, including Proof Key for Code Exchange (PKCE) for authorization code exchanges. A client's client_id comes from one of three places:

1. Pre-registration: Resend issues a fixed client_id, plus a client_secret if the client has a backend.
2. Client ID Metadata Document (CIMD): the client_id is the HTTPS URL of a JSON document you host, which Resend fetches to read the client's metadata.
3. Dynamic Client Registration (DCR): the client registers itself at runtime via POST /oauth/register and is issued a client_id then.

Prefer CIMD over DCR: it gives the client one identity across every install instead of a new registration each time, and the consent screen can name the host that published the document rather than a name the client picked for itself.

Resend supports both public and confidential clients. PKCE is required on every authorization code exchange regardless of type:

• Public clients authenticate with PKCE alone. Register them with token_endpoint_auth_method: "none" (the default), or declare that value in the metadata document. Use a public client when it can't keep a secret, such as native apps, CLIs, and single-page apps. A CIMD client is always public, since its document is world-readable and can't carry a secret.
• Confidential clients additionally present a client_secret at the token and revocation endpoints. Register them with token_endpoint_auth_method: "client_secret_basic" (or client_secret_post) to have Resend issue the secret. Use a confidential client when it has a backend that can store the secret privately, such as a server-side web app.

Because Resend does not offer self-service verification or domain-ownership checks yet, pre-register remote third-party clients rather than registering them dynamically, but you can register them with the same register endpoint.

The Resend dashboard hosts the login and consent screen. Your client only needs to open the authorization URL in a browser and handle the callback. You don't build any consent UI yourself.

The standard case is registering beforehand, and the worked examples below use it. A metadata document is the next best thing for clients that can't predict their own deployment details ahead of time, like an MCP server: it works for hosted apps and local tools alike, and one document serves every install. Register dynamically only when the client can't host a document.

Also decide whether the client is public or confidential. A client running entirely on the user's machine, such as a native app, CLI, or single-page app, can't hide a secret, so register it as public (none). A client with a server-side backend should register as confidential (client_secret_basic) and keep the issued client_secret out of any user-facing code. That choice only applies to a registered client, since a CIMD client is always public. The pre-registered remote client section below covers the confidential path, and the local client section covers the public one.

Use the smallest scope that works for your integration:

• emails:send is enough for send-only routes, such as POST /emails, POST /email, POST /emails/sending, POST /email/sending, and POST /broadcasts/:broadcastId/send.
• full_access is required for other API routes.

A client that omits scope gets both scopes by default, whether it registered dynamically or declared no scope in its metadata document. Pass scope explicitly during registration and authorization instead of relying on that default.

Dynamic client registration uses JSON, and so does a metadata document. The token and revocation endpoints accept both JSON and application/x-www-form-urlencoded, but prefer form encoding for /oauth/token and /oauth/revoke, since that's what most OAuth libraries send by default.

Resend does not support RFC 8707 resource indicators yet. Don't send or rely on resource in authorization or token requests. It's accepted but ignored.

Before starting the authorization request, generate three values:

• code_verifier: a high-entropy random string kept only by the client. See Token for the length and character set it must use.
• code_challenge: the base64url-encoded SHA-256 hash of the code_verifier.
• state: a high-entropy random string used to bind the callback to the request that started the flow.

The code_verifier is sent only during the token exchange. The code_challenge is sent during authorization. The state is sent during authorization and must come back unchanged on the callback.

import { createHash, randomBytes } from 'node:crypto';

function base64url(input) {
  return Buffer.from(input).toString('base64url');
}

const codeVerifier = base64url(randomBytes(64));
const codeChallenge = base64url(
  createHash('sha256').update(codeVerifier).digest(),
);
const state = base64url(randomBytes(24));

For a remote client, store state and codeVerifier server-side before redirecting the user to us. For a local client, keep them in memory while the temporary callback server is running.

Instead of registering, host a JSON document that describes the client and pass its HTTPS URL as the client_id:

GET /oauth/authorize?client_id=https%3A%2F%2Fexample.com%2Foauth%2Fclient.json&response_type=code&...

Resend fetches that URL, reads the client metadata from it, and runs the rest of the flow exactly as it does for a registered client. There's no registration call and no issued client_id to store. The client hardcodes its own document URL, and sends the same value as client_id at /oauth/token and /oauth/revoke.

This follows the OAuth Client ID Metadata Document draft. The rules below are the parts specific to Resend.

Host the document on a site you control, whatever the client is. A hosted app serves it next to the app and lists its own https callback. A CLI or desktop app serves it on the vendor's website and lists loopback callbacks, since the document only has to name the client, not run it.

{
  "client_id": "https://example.com/oauth/client.json",
  "client_name": "Example App",
  "client_uri": "https://example.com",
  "logo_uri": "https://example.com/logo.png",
  "redirect_uris": ["https://example.com/oauth/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "scope": "emails:send"
}

The fields are the registration fields, with extra rules:

Apart from grant_types, a declaration Resend can't honor fails the whole document rather than being dropped from it. A client that declares private_key_jwt, for instance, gets an error rather than being downgraded to an unauthenticated one.

The URL is the client's identity, and it's compared as an exact string with no normalization. Serve the document at a URL that survives a parse-and-serialize round trip: lowercase host, no explicit :443, no . or .. segments. It must use https, have a path (https://example.com alone won't do), and carry no fragment and no userinfo. Maximum 2048 characters.

Treat the URL as permanent. Moving the document makes a different client, and every user has to authorize again.

A document proves that you control its host, and nothing else:

• An https redirect URI must be on the same host as the document URL. A document at https://example.com/oauth/client.json can't name a callback on app.example.net.
• Loopback http URIs (127.0.0.1, localhost, [::1]) are exempt. A loopback address names the user's own machine rather than a publisher, so there's nothing to compare. Port variance works the same way it does for a registered client.
• Private-use URI schemes (e.g. cursor://) are exempt too, since they carry no web host at all.

Resend fetches the document when a browser hits /oauth/authorize.

• Redirects aren't followed. Serve the document at the exact URL with a 2xx.
• 5 KB maximum, 5 second timeout. A real document is a few hundred bytes.
• The document must be reachable. A fetch that fails, or a document that doesn't validate, fails the authorization with invalid_client. Resend won't fall back to an older copy, since a stale document can name a redirect URI you no longer control.
• cache-control: max-age is honored, clamped between 5 minutes and 24 hours. A document sent with no-store still gets the 5-minute floor.

Only /oauth/authorize fetches. Token, refresh, and revoke requests use the copy Resend already holds, so a document that's briefly unreachable doesn't break clients that already have a grant.

Because of the 5-minute floor, allow time for an edit to take effect. If a CDN caches the file too, the two windows stack.

Resend has no self-service verification yet, so a CIMD client is unverified. The consent screen headlines the document's host rather than client_name, since the host is the part Resend can check. client_name is shown as the client's own claim about itself.

Being unverified affects errors too. Once client_id and redirect_uri are validated, /oauth/authorize redirects an error back to the callback only when the target is a loopback address, a private-use scheme, or a verified client. An unverified https callback gets a JSON error instead, which stops the endpoint from being used as an open redirect. Handle both.

A remote client must use an HTTPS redirect URI owned by the app, for example https://example.com/oauth/callback.

Because a remote client has a backend that can keep a secret, register it as confidential: pass token_endpoint_auth_method: "client_secret_basic" and store the client_secret Resend returns. That secret is shown only once at registration, so persist it securely and never expose it in browser or client-side code. It's then presented on every token and revocation call, in addition to PKCE.

For remote apps, you can still use POST /oauth/register manually while we don't have a central place in the app to create clients.

sequenceDiagram
    autonumber
    participant C as App backend
    participant B as User browser
    participant AS as Resend OAuth API
    participant D as Resend dashboard

    Note over C: Generate PKCE values and state<br>Store alongside the user's session

    C->>B: 302 redirect to /oauth/authorize URL
    B->>AS: GET /oauth/authorize<br>client_id, redirect_uri, scope,<br>state, code_challenge
    AS-->>B: 302 redirect to dashboard consent URL
    B->>D: User reviews and approves request
    D-->>B: 302 redirect_uri with code + state
    B->>C: Callback with code + state

    Note over C: Verify state against the stored session value

    C->>AS: POST /oauth/token<br>Basic auth (client_id + client_secret)<br>grant_type=authorization_code<br>code, redirect_uri, code_verifier
    AS-->>C: access_token + refresh_token

Example authorization URL:

GET /oauth/authorize?client_id=550e8400-e29b-41d4-a716-446655440000&response_type=code&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback&scope=emails%3Asend&state=STATE_VALUE&code_challenge=CODE_CHALLENGE_VALUE&code_challenge_method=S256 HTTP/1.1
Host: api.resend.com

Example code exchange. The -u flag sends the client_id and client_secret as HTTP Basic auth, so client_id isn't repeated in the body:

curl -X POST 'https://api.resend.com/oauth/token' \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     -u '550e8400-e29b-41d4-a716-446655440000:CLIENT_SECRET' \
     -d 'grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback&code_verifier=CODE_VERIFIER_VALUE'

A local client must use a loopback redirect URI or a private-use URI scheme, per RFC 8252. Prefer 127.0.0.1 with a random local port, for example http://127.0.0.1:49152/oauth/callback. A native app the operating system routes to can use its own scheme instead, such as cursor://oauth/callback.

Loopback redirect URIs allow port variance, whether they come from registration or from a metadata document. The host, path, and query string must still match, and localhost and 127.0.0.1 count as different hosts. For example, a client can declare http://127.0.0.1/oauth/callback and later authorize with http://127.0.0.1:49152/oauth/callback.

The sequence below registers dynamically. With a metadata document, skip the registration step: the client_id is the document's URL, and the loopback redirect URI is listed in the document.

sequenceDiagram
    autonumber
    participant C as Local client
    participant B as User browser
    participant AS as Resend OAuth API
    participant D as Resend dashboard

    Note over C: Bind loopback callback server<br>Generate PKCE values and state

    C->>AS: POST /oauth/register<br>loopback redirect_uri, minimum scope
    AS-->>C: client_id

    C->>B: Open /oauth/authorize URL
    B->>AS: GET /oauth/authorize<br>client_id, redirect_uri, scope,<br>state, code_challenge
    AS-->>B: 302 redirect to dashboard consent URL
    B->>D: User reviews and approves request
    D-->>B: 302 redirect_uri with code + state
    B->>C: Callback with code + state

    Note over C: Verify state, then close the server

    C->>AS: POST /oauth/token<br>grant_type=authorization_code<br>code, redirect_uri, code_verifier
    AS-->>C: access_token + refresh_token

Close the loopback server after success or timeout.

Pass scope explicitly. If DCR omits scope, Resend registers the client with both scopes by default.

curl -X POST 'https://api.resend.com/oauth/register' \
     -H 'Content-Type: application/json' \
     -d $'{
  "client_name": "Example Local OAuth Client",
  "redirect_uris": ["http://127.0.0.1/oauth/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "scope": "emails:send"
}'

The response returns a UUID client_id:

{
  "client_id": "550e8400-e29b-41d4-a716-446655440000",
  "client_id_issued_at": 1750000000,
  "client_name": "Example Local OAuth Client",
  "redirect_uris": ["http://127.0.0.1/oauth/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "scope": "emails:send"
}

Do not have a backend or CLI process prefetch /oauth/authorize and then open the returned dashboard URL. Instead, open the authorization URL in the user's browser and let the browser follow the redirect to the dashboard.

const authorizationUrl = new URL('https://api.resend.com/oauth/authorize');
authorizationUrl.search = new URLSearchParams({
  client_id: '550e8400-e29b-41d4-a716-446655440000',
  response_type: 'code',
  redirect_uri: 'http://127.0.0.1:49152/oauth/callback',
  scope: 'emails:send',
  state,
  code_challenge: codeChallenge,
  code_challenge_method: 'S256',
}).toString();

openBrowser(authorizationUrl.toString());

After approval, Resend redirects back to the exact redirect_uri used in the authorization request:

GET /oauth/callback?code=AUTHORIZATION_CODE&state=STATE_VALUE HTTP/1.1
Host: 127.0.0.1:49152

Verify that the returned state matches the original state before exchanging the code.

The redirect_uri in the token request must match the redirect_uri from the authorization request.

curl -X POST 'https://api.resend.com/oauth/token' \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     -d 'grant_type=authorization_code&client_id=550e8400-e29b-41d4-a716-446655440000&code=AUTHORIZATION_CODE&redirect_uri=http%3A%2F%2F127.0.0.1%3A49152%2Foauth%2Fcallback&code_verifier=CODE_VERIFIER_VALUE'

The response includes a JWT access token and an opaque refresh token:

{
  "access_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6Im9hdXRoX2tleSIsInR5cCI6ImF0K2p3dCJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "JcL7aYfE7S9h3L4qv0o2e1w8m6n5b3x9RkP2tD4uV6Q",
  "scope": "emails:send"
}

Refresh tokens rotate on every successful refresh. Serialize refresh operations for a grant, and store the new refresh token atomically with the rest of the response. If refresh succeeds but the new refresh token isn't persisted, you'll need to reauthorize. Retrying an old token from multiple workers can revoke the whole grant: a replay fails with invalid_grant either way, and it also revokes the grant unless the rotation happened within the last minute. Don't rely on that window. See Token for the reuse-detection details.

Each refresh resets the new token's 60-day lifetime, so a client that refreshes regularly never has to reauthorize.

curl -X POST 'https://api.resend.com/oauth/token' \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     -d 'grant_type=refresh_token&client_id=550e8400-e29b-41d4-a716-446655440000&refresh_token=JcL7aYfE7S9h3L4qv0o2e1w8m6n5b3x9RkP2tD4uV6Q'

To disconnect a client, revoke the refresh token:

curl -X POST 'https://api.resend.com/oauth/revoke' \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     -d 'client_id=550e8400-e29b-41d4-a716-446655440000&token=JcL7aYfE7S9h3L4qv0o2e1w8m6n5b3x9RkP2tD4uV6Q&token_type_hint=refresh_token'

A confidential client must authenticate this request too, the same way it does at the token endpoint. For example, pass its client_secret with curl -u 'CLIENT_ID:CLIENT_SECRET' instead of sending client_id in the body.

Access tokens are JWTs and can't be revoked individually. Revoking the refresh token revokes the grant. See Revoke Token.