Authentication & Client Initialization

Relevant source files

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

• README.md
• examples/api_keys.go
• api_keys_test.go
• examples/send_email.go
• examples/webhook_receiver.go
• webhooks.go

Authentication and client initialization are the primary steps for interacting with the Resend API. The Resend Go SDK uses API keys to authenticate requests and provides a centralized Client structure to manage service-specific sub-clients. This system ensures that all outbound API calls include the necessary credentials while providing a structured interface for managing resources like emails, domains, and API keys themselves.

Client Initialization

To interact with the Resend API, you must initialize a new client using an API key retrieved from the Resend Dashboard. The resend.NewClient(apiKey) function creates a Client instance that serves as the entry point for all service operations.

apiKey := os.Getenv("RESEND_API_KEY")
client := resend.NewClient(apiKey)

Sources: README.md:31-33, examples/api_keys.go:17, examples/send_email.go:17

Client Architecture

The Client acts as a coordinator for multiple specialized service implementations. It maintains the authentication state and provides access to sub-services via public fields.

Service Field	Description
Emails	Handles sending, retrieving, and listing emails.
ApiKeys	Manages project API keys (create, list, delete).
Domains	Handles domain verification and management.
Webhooks	Manages webhook endpoints and signature verification.
Templates	Manages email templates and variables.

Sources: examples/api_keys.go:24-49, examples/send_email.go:34-45, webhooks.go:210-212, CHANGELOG.md:14-25

The following diagram illustrates the initialization flow and the relationship between the main client and its sub-services:

The diagram shows how a single API key initializes a central client that exposes specialized services.

API Key Management

The SDK allows you to manage API keys programmatically through the ApiKeys service. This is useful for rotating keys or creating scoped credentials for different environments.

Creating and Updating Keys

You create an API key by providing a name. The response contains a Token which must be stored securely, as it is only returned once during creation.

params := &resend.CreateApiKeyRequest{
    Name: "Production Key",
}
resp, err := client.ApiKeys.CreateWithContext(ctx, params)
// resp.Token contains the actual API key string

Sources: examples/api_keys.go:20-27, api_keys_test.go:27-38

API Key Data Structures

Field	Type	Description
Id	string	Unique identifier for the API key resource.
Name	string	Human-readable name assigned to the key.
Token	string	The actual secret key used for authentication (creation only).
CreatedAt	string	Timestamp when the key was generated.
LastUsedAt	*string	Optional timestamp of the most recent API request using this key.

Sources: api_keys_test.go:49-60, examples/api_keys.go:28-29

Webhook Verification

Beyond standard API authentication, the SDK provides tools for verifying incoming webhook requests. This process uses HMAC-SHA256 signature validation to ensure the request originated from Resend.

Verification Logic

The Webhooks.Verify method requires the raw payload body, specific headers (svix-id, svix-timestamp, svix-signature), and the SigningSecret obtained during webhook creation.

1. Timestamp Validation: Compares the svix-timestamp against the current time. If the difference exceeds 300 seconds (5 minutes), the request is rejected to prevent replay attacks.
2. Signature Construction: Concatenates {id}.{timestamp}.{payload}.
3. HMAC Calculation: Computes the HMAC-SHA256 hash using the decoded SigningSecret.
4. Constant-Time Comparison: Compares the computed signature against the received signature in the headers using constant-time comparison to prevent timing attacks.

Sources: webhooks.go:377-434, examples/webhook_receiver.go:43-56

The sequence diagram details the cryptographic handshake performed to verify webhook authenticity.

Conclusion

Authentication in the Resend Go SDK is centered around the Client object, which consumes a single API key to provide authenticated access to various services. The system supports full lifecycle management of API keys and advanced security features such as HMAC-SHA256 webhook verification to protect against unauthorized access and replay attacks.