API Key Provisioning
Relevant source files
The following files were used as context for generating this wiki page:
- src/main/java/com/resend/services/apikeys/ApiKeys.java
- src/main/java/com/resend/services/apikeys/model/ApiKey.java
- src/main/java/com/resend/services/apikeys/model/CreateApiKeyOptions.java
- src/main/java/com/resend/services/apikeys/model/CreateApiKeyResponse.java
- src/main/java/com/resend/services/apikeys/model/UpdateApiKeyOptions.java
- src/main/java/com/resend/Resend.java
- src/main/java/com/resend/core/net/impl/HttpClient.java
- src/test/java/com/resend/services/apikeys/ApiKeysTest.java
The API Key Provisioning module manages the lifecycle of authentication tokens within the Resend ecosystem. It provides programmatic interfaces to create, list, update, and delete API keys, allowing developers to manage access control for their domains and services.
This module resides within the com.resend.services.apikeys package and interacts with the Resend REST API via the HttpClient. You typically access these services through the main Resend client entry point.
Sources: src/main/java/com/resend/services/apikeys/ApiKeys.java:18-20, src/main/java/com/resend/Resend.java:94-96
Architecture and Service Entry
The ApiKeys class extends BaseService and acts as the primary controller for API key operations. It requires an existing API key for authentication and an implementation of IHttpClient to perform network requests.
The diagram shows the relationship between the main SDK entry point and the specialized API key service.
Sources: src/main/java/com/resend/Resend.java:94-96, src/main/java/com/resend/services/apikeys/ApiKeys.java:27-42
API Key Lifecycle Operations
Creating API Keys
To create a new key, you use the create method with CreateApiKeyOptions. This method performs a POST request to the /api-keys endpoint. The response includes the generated token, which is only visible at the time of creation.
The sequence diagram illustrates the flow of creating a new API key and receiving the secret token.
Sources: src/main/java/com/resend/services/apikeys/ApiKeys.java:49-52, src/main/java/com/resend/core/net/impl/HttpClient.java:117-133
Listing and Pagination
The list method retrieves metadata for existing keys. It supports pagination through ListParams, which allows setting limits on the number of returned items.
| Feature | Description | Source |
|---|---|---|
| Simple List | Retrieves all API keys without filters. | ApiKeys.java:60 |
| Paginated List | Uses ListParams to handle large sets of keys. | ApiKeys.java:71 |
| Metadata | Returns ID, Name, Created Date, and Last Used timestamp. | ApiKey.java:12-22 |
Sources: src/main/java/com/resend/services/apikeys/ApiKeys.java:60-75, src/main/java/com/resend/services/apikeys/model/ApiKey.java:12-22
Updating and Deletion
You can rename an existing API key using the update method. Deletion is performed via the remove method, which sends a DELETE request to the specific resource ID. Unlike other methods that return response objects, remove returns a boolean indicating success.
Sources: src/main/java/com/resend/services/apikeys/ApiKeys.java:85-108, src/test/java/com/resend/services/apikeys/ApiKeysTest.java:101-110
Data Models
Request Options
The SDK uses builder patterns for configuring provisioning requests.
CreateApiKeyOptions Fields:
| Field | Type | Description |
|---|---|---|
name | String | A descriptive name for the API key. |
permission | String | Access level (e.g., "full_access"). |
domain_id | String | Optional restriction to a specific domain. |
Sources: src/main/java/com/resend/services/apikeys/model/CreateApiKeyOptions.java:12-20
Response Structures
The creation response is unique because it contains the token string required for future authentication.
// Simplified structure of a successful creation response
public class CreateApiKeyResponse {
private String id; // The unique identifier for management
private String token; // The actual API key value (re_...)
}
Sources: src/main/java/com/resend/services/apikeys/model/CreateApiKeyResponse.java:8-14
Error Handling
Provisioning operations throw a ResendException if the API returns a non-successful status code (e.g., 401 Unauthorized, 422 Validation Error, or 404 Not Found). The exception contains the HTTP status code and the error message body returned by the server.
Sources: src/main/java/com/resend/services/apikeys/ApiKeys.java:103-105, src/test/java/com/resend/services/apikeys/ApiKeysTest.java:56-65
Network Implementation
The HttpClient class manages the technical details of the communication. For every provisioning request, it attaches a User-Agent identifying the SDK version and a Bearer token in the Authorization header.
The flowchart describes the internal logic of the network layer when processing API key operations.
Sources: src/main/java/com/resend/core/net/impl/HttpClient.java:117-133, src/main/java/com/resend/services/apikeys/ApiKeys.java:101-106