OAuth Grants Management

Relevant source files

The following files were used as context for generating this wiki page:

• src/commands/oauth-grants/index.ts
• src/commands/oauth-grants/list.ts
• src/commands/oauth-grants/revoke.ts
• src/commands/oauth-grants/utils.ts
• src/lib/oauth.ts
• src/lib/config.ts
• src/commands/auth/login.ts

The OAuth Grants Management system provides tools to monitor and control third-party applications authorized to access a Resend team. It allows users to view a durable record of all client authorizations and immediately terminate access when necessary.

Each OAuth grant represents a unique relationship between a client application and a team. The CLI manages these grants through the oauth-grants command group, supporting both active and historical (revoked) records.

Sources: src/commands/oauth-grants/index.ts:7-13, src/commands/oauth-grants/list.ts:11-14

Command Architecture

The system is organized into a primary command group with two main subcommands: list (aliased as ls) and revoke.

List Command

The list command retrieves all OAuth grants for the team. It supports forward and backward pagination through the Resend API. By default, the command displays a formatted table in interactive mode or raw JSON in non-interactive environments.

Sources: src/commands/oauth-grants/list.ts:11-18, src/commands/oauth-grants/list.ts:47-65

Revoke Command

The revoke command invalidates an OAuth grant. Revocation is immediate and irreversible. It causes all associated access and refresh tokens to stop working instantly.

Sources: src/commands/oauth-grants/index.ts:13, src/commands/oauth-grants/revoke.ts:11-14

Authentication and Token Lifecycle

The CLI manages OAuth authentication using Proof Key for Code Exchange (PKCE). It handles the initial authorization, code exchange, and automated token refreshing.

Authentication Flow

The CLI generates a code verifier and challenge to secure the authentication process. It starts a temporary local HTTP server to capture the authorization code from the browser callback.

The diagram shows the sequence for obtaining a new OAuth grant via PKCE and local callback.
Sources: src/lib/oauth.ts:178-189, src/lib/oauth.ts:241-267, src/commands/auth/login.ts:135-180

Token Refresh Logic

The CLI refreshes tokens automatically when the access token is near expiry. It checks the exp claim in the JWT access token and uses a 60-second leeway. If the refresh fails, the user must re-authenticate.

Sources: src/lib/oauth.ts:86-118, src/lib/config.ts:518-535

Data Persistence

OAuth grants are stored based on the availability of secure storage on the host system.

Storage Method	Condition	Implementation
Secure Storage	System keychain available	Tokens are stored in the OS keychain; only non-secret metadata (scopes) resides in credentials.json.
Plaintext File	No keychain available	The full grant, including access and refresh tokens, is stored directly in credentials.json.

Sources: src/lib/config.ts:730-779, src/commands/auth/login.ts:311-325

Data Models

The system uses the following structure for OAuth grant data and responses.

OAuth Grant Fields

Field	Type	Description
id	string	Unique identifier for the grant.
client_id	string	ID of the authorized application.
scopes	string[]	List of permissions granted (e.g., emails:send).
created_at	string	Timestamp of authorization.
revoked_at	string | null	Timestamp of revocation, or null if active.
revoked_reason	string | null	Reason for revocation (e.g., revoked_from_api).
client.name	string	Human-readable name of the application.

Sources: src/commands/oauth-grants/list.ts:28-31, src/commands/oauth-grants/utils.ts:13-19

Grant Revocation Logic

Revocation requires explicit confirmation to prevent accidental access loss.

1. Item Selection: If no ID is provided, the CLI uses a picker configuration to fetch and display active grants for the user to choose from.
2. Confirmation:
   • Interactive: The CLI prompts the user with a warning about immediate token invalidation.
   • Non-Interactive: The --yes flag is mandatory. If absent, the CLI exits with a confirmation_required error.
3. Execution: The CLI calls the resend.oauthGrants.revoke SDK method.

The flowchart describes the decision logic for revoking an OAuth grant.
Sources: src/commands/oauth-grants/revoke.ts:30-51, src/commands/oauth-grants/utils.ts:6-11

Conclusion

OAuth Grants Management ensures team security by providing visibility into authorized applications and a mechanism for immediate revocation. The system prioritizes security through PKCE-based authentication and leverages system keychains for token persistence when available.

Sources: src/commands/oauth-grants/index.ts:7-13, src/lib/config.ts:730-750