OAuth Grants

Relevant source files

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

• oauth_grants.go
• examples/oauth_grants.go
• oauth_grants_test.go
• examples/with_pagination.go
• examples/api_keys.go
• CHANGELOG.md

The OAuth Grants module manages the permissions granted to third-party applications or clients (such as the Resend CLI) to access your Resend account. It provides functionality to audit existing access and revoke specific grants when they are no longer needed.

This module resides within the resend-go SDK and communicates with the Resend API via the OAuthGrantsSvc interface. You use this service to retrieve lists of active grants, view specific metadata about the granting client, and programmatically terminate access sessions.

Sources: oauth_grants.go, examples/oauth_grants.go:11-15

Data Models and Architecture

The system represents every authorized connection as an OAuthGrant object. Each grant contains specific identifying information about the client and the scope of access granted.

Data Structures

Field	Type	Description
Id	string	Unique identifier for the grant.
ClientId	string	Unique identifier for the third-party application.
Scopes	[]string	List of permissions authorized (e.g., emails:send).
CreatedAt	string	The timestamp when the grant was created.
RevokedAt	*string	The timestamp when access was removed (null if active).
RevokedReason	*string	Explanation for the revocation (e.g., revoked_from_api).
Client	OAuthGrantClient	Metadata about the application, including name and logo.

Sources: oauth_grants.go:9-25, oauth_grants_test.go:25-45

Entity Relationships

The following diagram illustrates the relationship between an OAuth grant and its associated client metadata.

The diagram shows that every OAuthGrant is associated with exactly one OAuthGrantClient which provides human-readable details about the application.

Sources: oauth_grants.go:9-25

Service Operations

The OAuthGrantsSvc interface defines the primary interactions available for managing grants. The implementation, OAuthGrantsSvcImpl, handles the construction of HTTP requests and the parsing of API responses.

Listing Grants

You retrieve grants using the List, ListWithContext, or ListWithOptions methods. The listing operation supports pagination through the standard ListOptions structure.

• Endpoint: GET /oauth/grants
• Response: ListOAuthGrantsResponse containing a slice of OAuthGrant objects and a HasMore boolean for pagination.

Sources: oauth_grants.go:27-35, oauth_grants.go:46-67

Revoking Access

To terminate a specific grant, you use the Revoke or RevokeWithContext methods. This action permanently disables the associated access token.

• Endpoint: DELETE /oauth/grants/{oauthGrantId}
• Response: RevokeOAuthGrantResponse containing the revocation timestamp and reason.

Sources: oauth_grants.go:70-87, examples/oauth_grants.go:27-35

API Interaction Flow

The following sequence diagram demonstrates the flow of a revocation request through the SDK to the Resend API.

The diagram illustrates how the service implementation abstracts the complexity of manual HTTP request handling and JSON unmarshaling.

Sources: oauth_grants.go:70-87

Implementation Examples

Listing Active Grants

This example demonstrates how to check the number of active OAuth grants in your account.

client := resend.NewClient(apiKey)
grants, err := client.OAuthGrants.List()
if err != nil {
    panic(err)
}
fmt.Printf("You have %d OAuth grants\n", len(grants.Data))

Sources: examples/oauth_grants.go:17-21

Conditional Revocation

The SDK allows you to revoke access and inspect the reason provided by the API.

// Revoke the first grant in the list
revoked, err := client.OAuthGrants.RevokeWithContext(ctx, grants.Data[0].Id)
if err != nil {
    panic(err)
}

reason := "unknown"
if revoked.RevokedReason != nil {
    reason = *revoked.RevokedReason
}
fmt.Printf("Revoked OAuth grant %s (reason: %s)\n", revoked.Id, reason)

Sources: examples/oauth_grants.go:27-36

Summary of Pagination Support

The OAuth Grants listing follows the same cursor-based pagination pattern used by other Resend services like Domains and API Keys. You provide a limit and an after cursor in the ListOptions to navigate through large sets of grants.

Sources: oauth_grants.go:47, examples/with_pagination.go:16-30