API Key Management
Relevant source files
The following files were used as context for generating this wiki page:
API Key Management handles the lifecycle of authentication tokens used to communicate with the Resend API. The system enables the creation, retrieval, naming, and deletion of keys, while providing options to restrict keys by domain or permission level.
The IResend interface serves as the primary entry point for managing these credentials. Developers use these methods to programmatically control access to their Resend account resources.
Sources: src/Resend/IResend.cs:326-376, src/Resend/README.md:15-18
Data Models
The system represents API keys through two primary structures: one for general metadata and one specifically for the initial creation event that includes the secret token.
ApiKey and ApiKeyData
- ApiKey: Represents an existing key in the account. It contains the unique identifier, the user-defined name, and the timestamp of creation.
- ApiKeyData: Returned only during the creation process. It includes the
Token(the actual secret key string) which the Resend API does not reveal in subsequent list or retrieve calls.
Sources: src/Resend/ApiKey.cs:5-46
Request Payloads
Operations that modify API keys use dedicated payload classes to ensure type safety and correct JSON serialization.
- ApiKeyCreateRequest: Encapsulates the name, optional permissions, and optional domain restriction for a new key.
- ApiKeyUpdateRequest: Limits updates to the display name of the key.
Sources: src/Resend/Payloads/ApiKeyCreateRequest.cs:8-28, src/Resend/Payloads/ApiKeyUpdateRequest.cs:8-13
Entity Relationship Diagram
The following diagram shows the relationship between the client interface and the data models used during key management.
The diagram illustrates that IResend acts as the orchestrator for all API key entities.
Sources: src/Resend/IResend.cs:326-376, src/Resend/ApiKey.cs:5-46
API Operations
The IResend interface defines four primary asynchronous operations for managing API keys.
| Operation | Description | Return Type |
|---|---|---|
ApiKeyListAsync | Retrieves a list of all defined API keys. | List<ApiKey> |
ApiKeyCreateAsync | Adds a new API key with specific permissions. | ApiKeyData |
ApiKeyUpdateAsync | Renames an existing API key. | Guid |
ApiKeyDeleteAsync | Removes an existing API key. | Task |
Sources: src/Resend/IResend.cs:326-376
Key Creation Flow
When you create a key, you define its name and scope. If the permission is set to FullAccess, you can further restrict the key to a specific domain by providing a domainId.
This flow demonstrates the creation process where the secret token is returned exactly once.
Sources: src/Resend/IResend.cs:337-355, tools/Resend.ApiServer/Controllers/ApiKeyController.cs:22-34
Key Updates and Deletion
The SDK restricts updates to renaming only. You cannot change the permissions or domain restrictions of an existing key; to modify these properties, you must delete the existing key and create a new one.
- Update: Sends a
PATCHrequest to/api-keys/{id}. - Delete: Sends a
DELETErequest to/api-keys/{id}.
Sources: src/Resend/IResend.cs:357-376, tools/Resend.ApiServer/Controllers/ApiKeyController.cs:36-84
Technical Implementation Details
JSON Property Mapping
The models use JsonPropertyName attributes to map C# PascalCase properties to the snake_case expected by the Resend REST API.
| Model Property | JSON Field | File |
|---|---|---|
ApiKey.MomentCreated | created_at | ApiKey.cs |
ApiKeyCreateRequest.DomainId | domain_id | ApiKeyCreateRequest.cs |
ApiKeyData.Token | token | ApiKey.cs |
Sources: src/Resend/ApiKey.cs:1-46, src/Resend/Payloads/ApiKeyCreateRequest.cs:1-28
Code Snippet: Interface Definition
// src/Resend/IResend.cs:337-376
Task<ResendResponse<List<ApiKey>>> ApiKeyListAsync( CancellationToken cancellationToken = default );
Task<ResendResponse<ApiKeyData>> ApiKeyCreateAsync( string keyName, Permission? permission = null, Guid? domainId = null, CancellationToken cancellationToken = default );
Task<ResendResponse<Guid>> ApiKeyUpdateAsync( Guid apiKeyId, string name, CancellationToken cancellationToken = default );
Task<ResendResponse> ApiKeyDeleteAsync( Guid apiKeyId, CancellationToken cancellationToken = default );
Sources: src/Resend/IResend.cs:337-376
Summary
API Key Management in the Resend .NET SDK provides a secure and structured way to handle access credentials. The implementation separates public metadata (ApiKey) from sensitive creation data (ApiKeyData) and enforces a clean update policy where security-critical attributes like permissions remain immutable post-creation.