API Keys Management

Relevant source files

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

• src/api-keys/api-keys.ts
• src/api-keys/api-keys.spec.ts
• src/api-keys/api-keys.integration.spec.ts
• src/resend.ts
• src/request-options.spec.ts

The API Keys Management system allows you to programmatically create, list, update, and remove API keys used to authenticate requests to the Resend API. This module provides the ApiKeys class, which interacts with the /api-keys endpoints to manage security credentials and their associated permissions.

Sources: src/api-keys/api-keys.ts, src/resend.ts:58

Core Architecture

The ApiKeys module is a sub-resource of the main Resend client. It uses the internal HTTP methods provided by the Resend class to perform RESTful operations.

Component Relationship

The following diagram shows how the ApiKeys class interacts with the main Resend client and the external API.

The ApiKeys class receives an instance of Resend in its constructor, allowing it to share authentication headers and base URL configurations.

Sources: src/api-keys/api-keys.ts:24, src/resend.ts:58

API Key Operations

Creating API Keys

You create API keys by providing a name and optional permissions. The API returns a unique ID and the plaintext token, which is only shown once during creation.

Parameter	Type	Description
name	string	Descriptive name for the key.
permission	string	Access level: full_access or sending_access.
domain_id	string	(Optional) Restricts the key to a specific domain.

Sources: src/api-keys/api-keys.spec.ts:31-41, src/api-keys/api-keys.spec.ts:114-120

Listing API Keys

The list method retrieves all API keys associated with the account. It supports cursor-based pagination using the limit, after, and before parameters.

Updating and Removing Keys

• Update: Modifies the name of an existing API key identified by its id.
• Remove: Deletes an API key permanently using its id.

Sources: src/api-keys/api-keys.ts:53-73

Data Structures

Create Response

When a key is successfully created, the API returns the following object structure:

Field	Type	Description
id	string	Unique identifier for the API key.
token	string	The actual API token used for authentication.

Sources: src/api-keys/api-keys.spec.ts:34-37

List Item Metadata

The listing operation returns metadata for each key:

Field	Type	Description
id	string	Unique identifier.
name	string	User-defined name.
created_at	string	Timestamp of creation.
last_used_at	string or null	Timestamp of the last API call made with this key.

Sources: src/api-keys/api-keys.spec.ts:153-166

Error Handling

The module handles validation and lifecycle errors returned by the API. Common errors include:

• validation_error (422): Occurs when the name is empty or permissions are invalid.
• not_found (404): Occurs when trying to update or remove a key with a non-existent ID.
• application_error (500): Occurs during internal server failures.

Sources: src/api-keys/api-keys.spec.ts:74-85, src/api-keys/api-keys.spec.ts:285-295

Request Customization

Every method in the ApiKeys class accepts an optional requestOptions object. This allows you to:

• Pass custom headers (e.g., X-Trace-Id).
• Provide an AbortSignal to cancel the request.
• Set an idempotencyKey for the create operation.

Sources: src/request-options.spec.ts:15-18, src/request-options.spec.ts:158-172

Summary

The API Keys Management system provides a standard interface for maintaining the lifecycle of authentication credentials. It ensures secure creation with granular permissions and supports administrative tasks like auditing usage through the last_used_at field and rotating keys by removing and recreating them.