API Keys & Security Access
Relevant source files
The following files were used as context for generating this wiki page:
The Resend CLI manages authentication and security access through API keys and OAuth grants. This system ensures that every command executed against the Resend API is authorized and tracked according to specific permission levels.
The CLI resolves credentials from multiple sources, prioritizing explicit command-line flags over environment variables and local configuration files. It also supports secure storage backends to prevent sensitive keys from being stored in plaintext on the file system.
Authentication Resolution
The CLI uses a strictly defined hierarchy to resolve the API key for any given request. The resolveAuthentication function handles this logic by checking sources in a specific order.
The system identifies four primary sources for credentials:
- Flag: Explicitly passed via the
--api-keyglobal option. - Env: Loaded from the
RESEND_API_KEYenvironment variable. - Secure Storage: Retrieved from the OS keychain (e.g., macOS Keychain, Windows Credential Manager).
- Config: Read from the
credentials.jsonfile in the user's config directory.
Sources: src/lib/config.ts:34-42, src/lib/config.ts:414-436, skills/resend-cli/SKILL.md:65-67
Credential Types and Structures
The CLI supports two main types of authentication entities: standard API keys and OAuth grants.
API Keys
API keys are long-lived tokens that start with the prefix re_. They can be assigned specific permission levels.
| Permission | Description |
|---|---|
full_access | Grants access to all API operations including key management and domain settings. |
sending_access | Restricts the key to email-sending operations only (emails, broadcasts). |
Sources: src/lib/config.ts:32-33, src/lib/config.ts:25-30, src/commands/api-keys/index.ts:10-12
OAuth Grants
OAuth grants allow for temporary access based on user authorization. The CLI persists the access_token and refresh_token together.
- Access Token: Used for API authorization; contains an expiration claim.
- Refresh Token: Used to obtain a new access token when the current one expires.
- Scope: Defines the permissions granted to the token (e.g.,
full_access).
Sources: src/lib/config.ts:51-57, src/lib/config.ts:60-64
Security and Diagnostics
The CLI implements several measures to protect credentials and verify system health.
Credential Masking
To prevent accidental exposure in logs or terminal output, the CLI masks keys using the maskKey utility. This function typically shows the first three characters and the last four characters, replacing the middle with ellipses.
export function maskKey(key: string): string {
if (key.length <= 7) {
return `${key.slice(0, 3)}...`;
}
return `${key.slice(0, 3)}...${key.slice(-4)}`;
}
Sources: src/lib/config.ts:384-389, src/commands/doctor.ts:109-115
Health Checks (Resend Doctor)
The resend doctor command performs automated checks on the security environment.
- API Key Presence: Verifies if a key is found from any source without initiating a network call.
- Credential Storage: Identifies if the backend is "secure storage" (keychain) or a "plaintext file."
- API Validation: Exercises the key against the
/domainsendpoint to ensure it is valid and active.
Sources: src/commands/doctor.ts:93-118, src/commands/doctor.ts:149-165
API Key Management Flow
The api-keys command group manages the lifecycle of API keys. Key creation allows for domain-specific restrictions.
Constraints and Validation
- Confirmation: Deletion commands require the
--yesflag in non-interactive environments to prevent accidental data loss. - Visibility: Tokens are only displayed immediately after creation and cannot be retrieved again via the CLI or API.
- Domain Restriction: When creating a key with
sending_access, you can optionally provide a--domain-idto restrict that key to a single verified domain.
Sources: src/commands/api-keys/index.ts:10-15, tests/commands/api-keys/create.test.ts:153-172, skills/resend-cli/SKILL.md:126-128
Storage Configuration
The CLI stores configuration data in platform-specific directories.
- Linux/macOS:
~/.config/resend/credentials.json(or respectsXDG_CONFIG_HOME). - Windows:
%APPDATA%\resend\credentials.json.
The file is written with restrictive permissions (0o600) to ensure only the current user can read or write to it.