OAuth Grants

Relevant source files

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

• src/oauth-grants/oauth-grants.ts
• src/oauth-grants/oauth-grants.spec.ts
• src/oauth-grants/interfaces/oauth-grant.ts
• src/oauth-grants/interfaces/list-oauth-grants.interface.ts
• src/oauth-grants/interfaces/revoke-oauth-grant.interface.ts
• src/request-options.spec.ts

OAuth Grants provide a mechanism for managing third-party application permissions within the Resend platform. The OAuthGrants module allows developers to programmatically list and revoke these permissions, ensuring secure access control for integrated clients.

The module interfaces directly with the Resend API to handle authorization records, which include details about the client, the granted scopes (such as emails:send), and the status of the grant.

Sources: src/oauth-grants/oauth-grants.ts:1-32, src/oauth-grants/interfaces/oauth-grant.ts:1-14

Core Functionality

The OAuthGrants class exposes two primary methods to manage authorization: list and revoke. These methods interact with the /oauth/grants endpoint of the Resend API.

Listing OAuth Grants

The list method retrieves a paginated collection of OAuth grant objects. You can provide optional pagination parameters to control the number of results returned.

The diagram shows the logic flow for retrieving authorization records from the API.

Sources: src/oauth-grants/oauth-grants.ts:14-23, src/oauth-grants/oauth-grants.spec.ts:56-78

Revoking OAuth Grants

The revoke method invalidates a specific authorization by its unique identifier. Once revoked, the third-party client loses access associated with that grant.

The sequence diagram illustrates the request-response cycle for terminating a client's access.

Sources: src/oauth-grants/oauth-grants.ts:25-31, src/oauth-grants/oauth-grants.spec.ts:114-142

Data Models

The system uses specific interfaces to define the structure of authorization data and API interactions.

OAuthGrant Object

An OAuthGrant represents a single authorization granted to a client.

Field	Type	Description
id	string	Unique identifier for the grant record.
client_id	string	Unique identifier for the authorized application.
scopes	string[]	List of permissions granted (e.g., ['emails:send']).
created_at	string	ISO timestamp of when the grant was created.
revoked_at	string | null	ISO timestamp if revoked; otherwise null.
revoked_reason	string | null	Reason for revocation (e.g., revoked_from_api).
client.name	string	The display name of the application.

Sources: src/oauth-grants/interfaces/oauth-grant.ts:1-14, src/oauth-grants/oauth-grants.spec.ts:24-34

API Method Parameters

The methods accept standard configuration options to modify request behavior.

Method	Option	Type	Description
list	limit	number	Maximum number of records to return.
list	before	string	Pagination cursor for previous page.
list	after	string	Pagination cursor for next page.
All	requestOptions	RequestOptions	Custom headers or AbortSignal for the request.

Sources: src/oauth-grants/interfaces/list-oauth-grants.interface.ts:1-10, src/request-options.spec.ts:168-175

Class Definition and Logic

The OAuthGrants class is instantiated with a reference to the main Resend client to perform authenticated HTTP operations.

// src/oauth-grants/oauth-grants.ts:11-32
export class OAuthGrants {
  constructor(private readonly resend: Resend) {}

  async list(
    options: ListOAuthGrantsOptions = {},
    requestOptions: RequestOptions = {},
  ): Promise<ListOAuthGrantsResponse> {
    const url = buildPaginationUrl('/oauth/grants', options);
    return await this.resend.get<ListOAuthGrantsResponseSuccess>(url, requestOptions);
  }

  async revoke(
    id: string,
    requestOptions: RequestOptions = {},
  ): Promise<RevokeOAuthGrantResponse> {
    return await this.resend.delete<RevokeOAuthGrantResponseSuccess>(
      `/oauth/grants/${id}`,
      undefined,
      requestOptions,
    );
  }
}

Sources: src/oauth-grants/oauth-grants.ts:11-32

Error Handling

The module handles API failures by returning an error object within the response. A common error occurs when attempting to revoke an ID that does not exist or is already revoked, resulting in a 404 Not Found response.

Error Name	Status Code	Context
not_found	404	Returned by revoke if the grant ID is invalid or missing.
application_error	null	Returned if the request is aborted via AbortSignal.

Sources: src/oauth-grants/oauth-grants.spec.ts:154-165, src/request-options.spec.ts:248-260

Conclusion

OAuth Grants management is a critical component for security within the Resend ecosystem. It enables users to monitor active integrations and terminate access for specific clients via the SDK. This functionality integrates seamlessly with the standard pagination and request option patterns used throughout the Resend Node.js library.