OAuth Grants Management
Relevant source files
The following files were used as context for generating this wiki page:
The OAuth Grants Management module provides tools to view and revoke permissions granted to third-party applications. It allows you to audit which clients have access to your account and what specific actions (scopes) they can perform.
This module interfaces with the /oauth/grants API endpoint. It supports both synchronous and asynchronous operations to retrieve lists of active or revoked grants and to terminate specific authorizations.
Data Structures
The module defines the structure of OAuth grants and the clients they are associated with.
OAuthGrant Entity
The OAuthGrant represents a single authorization given to an application. It includes metadata about when the grant was created, its current status, and the associated client.
| Field | Type | Description |
|---|---|---|
id | str | Unique identifier for the grant. |
client_id | str | Unique identifier for the application client. |
scopes | List[str] | List of permissions granted (e.g., emails:send). |
created_at | str | ISO 8601 timestamp of creation. |
revoked_at | Optional[str] | ISO 8601 timestamp of revocation, if applicable. |
revoked_reason | Optional[str] | Reason for revocation (e.g., revoked_from_api). |
client | OAuthGrantClient | Metadata about the application client. |
Sources: resend/oauth_grants/_oauth_grant.py:17-40, tests/oauth_grants_test.py:16-29
OAuthGrantClient Entity
This object identifies the application that requested the grant.
| Field | Type | Description |
|---|---|---|
name | str | The display name of the application. |
logo_uri | Optional[str] | URL for the application's icon. |
Sources: resend/oauth_grants/_oauth_grant.py:6-14
Core Functionality
The OAuthGrants class provides methods for listing and revoking grants.
Retrieving Grants
You can retrieve a list of OAuth grants using the list() or list_async() methods. These methods support pagination through ListParams.
The diagram shows the flow of a list request from the user call to the path building and final request execution.
Sources: resend/oauth_grants/_oauth_grants.py:84-100, resend/oauth_grants/_oauth_grants.py:133-149
Revoking Grants
To terminate access for a specific application, you use the revoke() or revoke_async() method with a specific oauth_grant_id.
The sequence diagram illustrates the process of revoking an authorization.
Sources: resend/oauth_grants/_oauth_grants.py:116-129, tests/oauth_grants_test.py:133-146
API Parameters and Responses
Pagination Parameters
When listing grants, you can control the result set using ListParams.
| Parameter | Type | Description |
|---|---|---|
limit | int | Number of items to return (1 to 100). |
after | str | ID after which to retrieve results. |
before | str | ID before which to retrieve results. |
Sources: resend/oauth_grants/_oauth_grants.py:67-82
Response Wrappers
Methods return standardized response objects containing the data and metadata.
- ListResponse: Contains a
datalist ofOAuthGrantobjects and ahas_moreboolean for pagination. - RevokeOAuthGrantResponse: Confirms the ID and timestamp of the revocation.
Sources: resend/oauth_grants/_oauth_grants.py:22-65
Implementation Examples
Synchronous Usage
import resend
# List grants
grants = resend.OAuthGrants.list(params={"limit": 10})
for grant in grants["data"]:
print(grant["client"]["name"], grant["id"])
# Revoke a grant
if grants["data"]:
resend.OAuthGrants.revoke(oauth_grant_id=grants["data"][0]["id"])
Sources: examples/oauth_grants.py:8-23, examples/oauth_grants.py:38-42
Asynchronous Usage
import asyncio
import resend
async def run():
grants = await resend.OAuthGrants.list_async()
if grants["data"]:
await resend.OAuthGrants.revoke_async(grants["data"][0]["id"])
asyncio.run(run())
Sources: examples/async/oauth_grants_async.py:12-25
Summary
The OAuth Grants Management module ensures account security by providing visibility and control over third-party integrations. By using the OAuthGrants class, you can programmatically audit access and revoke specific grants using both synchronous and asynchronous Python patterns.