API Key Management: Secure Storage, Rotation, and Recovery

API key management is the discipline of controlling the credentials your application uses to call an API or authenticate to an SMTP relay. For a transactional email system, a leaked or over-permissioned key can become an expensive deliverability, security, and incident-response problem—not merely a broken integration.

An API key is often presented as a small implementation detail: paste a value into an environment variable, add an HTTP header, and send mail. In production, it is an identity with the ability to use a vendor account, consume quota, send messages, access sending data, or change resources depending on its permissions. Treat it with the same care you would give a production database password.

This guide is vendor-neutral. The same principles apply whether your application sends email through a REST API, an SMTP relay, a cloud platform, an internal mail service, or several providers at once.

What an API key is—and what it is not

An API key is a secret credential that identifies and authenticates a calling application or workload. A provider may expect it in an HTTP header, as a bearer token, in basic authentication, or as an SMTP username or password. The precise format differs by provider, but the important security property does not: anyone who possesses a valid secret may be able to act as the associated account or project.

For a REST email API, a request commonly looks like this:

curl https://api.email-provider.example/v1/send \
  -X POST \
  -H 'Authorization: Bearer '$EMAIL_API_KEY \
  -H 'Content-Type: application/json' \
  -d '{"from":"receipts@example.com","to":["customer@example.net"],"subject":"Your receipt","html":"<p>Thank you.</p>"}'

The endpoint, header name, and JSON schema in that example are deliberately generic. Do not copy an authentication scheme from a random tutorial: use the provider’s published API reference. If your application supports REST sending or SMTP relay, keep its delivery credentials in server-side configuration and follow the provider-specific setup guidance in the email API reference and setup guides.

An API key is not an email-authentication DNS record. It does not publish permission for receivers to trust a domain, and DNS records do not authorize your application to use an email provider account. These are separate layers:

• API key or SMTP credential: authorizes your software to submit mail through a service.
• SPF: tells receiving servers which infrastructure may send mail for an envelope sender domain.
• DKIM: lets a sender sign messages with a private key whose public key is published in DNS.
• DMARC: tells receivers how to evaluate alignment and what policy to apply when authentication fails.
• TLS: protects the transport connection between your app and the API or SMTP relay.

This distinction matters during debugging. A 401 Unauthorized response points to an API credential problem, while a 550 recipient rejection may reflect a destination, policy, or mailbox issue. A message accepted by a provider can still land in spam if domain authentication or content quality is weak.

Start with a key inventory and a clear ownership model

Strong API key management begins before a key is generated. You need to know which keys exist, who owns each one, what system uses it, what it can do, and when it was last used. Without that inventory, rotation turns into a risky scavenger hunt and a suspected leak becomes impossible to scope quickly.

Give every credential one job

Avoid a single all-powerful key called production-key that is shared by your website, background workers, staging environment, marketing import job, and a developer’s laptop. Instead, create separate credentials for distinct workloads and environments.

A practical email-related inventory might include:

Use a consistent name in your secret manager, deployment manifests, and internal runbook. For example:

email/prod/checkout-send/v3
email/prod/password-reset-send/v2
email/staging/integration-tests/v5

The version suffix is useful during rotation, but avoid putting the raw secret itself in the name, description, ticket title, pull request, or log line. A key identifier, prefix, or provider-generated label can help you correlate usage without exposing the credential value.

Assign a human owner and a system owner

Every production key should have both:

1. A human owner responsible for approving changes, reviewing alerts, and maintaining the runbook.
2. A system owner—the service, repository, deployment, or workload that consumes the secret.

This small distinction prevents a common failure mode: a team rotates a key after an employee leaves, then discovers that a scheduled job in an unrelated account still depends on it. The goal is not bureaucracy. The goal is being able to answer, in minutes rather than days, “What will stop working if we revoke this credential?”

Prefer scoped keys over account-wide keys

If a provider supports scopes, roles, IP restrictions, domain restrictions, expiration, or environment-specific credentials, use those features. A key that can only send mail is safer than one that can send mail, manage domains, read suppression data, alter webhooks, and invite account users.

Scope is particularly valuable for email because abuse has a direct operational cost. A stolen send-only key is still serious, but a key that also controls sender identities or access controls can expand the incident. Separate administrative credentials from runtime sending credentials whenever the service permits it.

Store keys outside source code

The first rule of API key management is simple: do not hardcode secrets into application code, frontend bundles, documentation examples, Docker images, or version-controlled configuration files.

A value committed once can persist in repository history, forks, clones, build caches, log archives, screenshots, and code-review tools long after it is removed from the current branch. Deleting the line is not a sufficient response; the credential must be treated as exposed and replaced.

Use a secret manager in production

A dedicated secret manager is the preferred production store. Examples include AWS Secrets Manager, AWS Systems Manager Parameter Store, Google Cloud Secret Manager, Azure Key Vault, HashiCorp Vault, and a managed secret store supplied by your deployment platform. These products differ, but the desirable capabilities are similar:

• Encryption at rest and encrypted transport.
• Fine-grained workload access control.
• Audit logs for secret reads and administrative changes.
• Versioning to support overlap during rotation.
• Automated or scheduled rotation workflows where appropriate.
• Separation between application code and credential administration.

Your runtime should receive permission to read only the secret it needs. A checkout service should not automatically be able to read every email, database, payment, and analytics secret in the organization. Apply least privilege to the secret store itself, not just to the email provider account.

Environment variables are a delivery mechanism, not a vault

Environment variables can be an acceptable way to inject a key into a process, especially when your hosting platform integrates with a secret manager. They are not inherently a secure secret-management system.

Environment variables can be exposed through debug endpoints, error reports, child-process inheritance, process-inspection tools, CI output, support bundles, or an overly broad platform role. Minimize their lifetime and visibility. Do not print an entire environment object to diagnose a deployment issue.

A local development file can look like this:

EMAIL_API_KEY=replace-with-a-development-only-secret
EMAIL_SMTP_USERNAME=replace-with-provider-username
EMAIL_SMTP_PASSWORD=replace-with-development-only-password

Put .env and environment-specific variants in .gitignore, provide a committed .env.example file containing placeholder values only, and use a development key that cannot affect production sending. A safe example file is useful; a copied production credential is not.

Keep secrets off the client

Never place a privileged email API key in browser JavaScript, a mobile app, a public static site, a browser extension, or any client-side configuration that users can inspect. Obfuscation, minification, encoding, and storing a key in a frontend environment variable do not make it secret.

Client-side code should call your own authenticated backend. The backend can then validate the user action, enforce business rules, rate-limit requests, select a trusted sender identity, and use the provider key privately. This design also prevents an attacker from using a publicly exposed mail credential to send arbitrary messages at your expense.

Use keys safely in REST APIs and SMTP relays

REST APIs and SMTP have different request formats, but the same core rule applies: send the credential only to the intended service over an authenticated encrypted connection.

REST API practices

For HTTP APIs, use HTTPS. Put the secret in the documented request header rather than in a query string unless the provider explicitly requires another mechanism. Query strings are especially risky because they are often captured in proxy logs, analytics tools, browser history, server access logs, and referrer headers.

Good operational patterns include:

• Set connection and request timeouts so a stalled service does not tie up workers indefinitely.
• Log request IDs, HTTP status codes, endpoint categories, and response error codes—but redact authorization headers and payload fields containing secrets or personal data.
• Use idempotency keys if the provider supports them, especially for retryable transactional messages such as receipts or password resets.
• Enforce outbound network rules where feasible so a runtime credential cannot be exfiltrated and used from arbitrary systems.
• Validate the provider hostname before making outbound requests; do not build it from untrusted user input.

A redaction helper should remove or replace sensitive fields before structured logs leave the process:

function redactHeaders(headers) {
  const copy = { ...headers };
  for (const name of Object.keys(copy)) {
    if (['authorization', 'x-api-key', 'api-key'].includes(name.toLowerCase())) {
      copy[name] = '[REDACTED]';
    }
  }
  return copy;
}

Do not rely only on a developer remembering not to log secrets. Build redaction into shared HTTP clients, observability middleware, incident tooling, and error-reporting configuration.

SMTP relay practices

SMTP integrations commonly authenticate with a username and password, often using the API key as the password or using a provider-specific generated SMTP credential. Do not assume your REST API key and SMTP password are interchangeable. Follow the relay’s documented hostname, port, TLS mode, and authentication method.

Typical SMTP submission configurations use port 587 with STARTTLS or port 465 with TLS from connection start, but the supported ports and requirements are provider-specific. Port 25 is often filtered by cloud hosts and is generally a poor application-submission default. Configure certificate verification; a setting that disables TLS verification may make troubleshooting appear easier while opening a path to credential interception.

A generic Node.js-style configuration might resemble:

const transport = createTransport({
  host: process.env.EMAIL_SMTP_HOST,
  port: 587,
  secure: false,
  requireTLS: true,
  auth: {
    user: process.env.EMAIL_SMTP_USERNAME,
    pass: process.env.EMAIL_SMTP_PASSWORD
  }
});

That code does not establish that port 587 or this authentication shape works for every relay. It shows the separation you want: configuration and credentials come from protected runtime settings, not from source code.

Do not confuse SMTP authentication with domain authentication

Your SMTP login proves to the relay that your application may submit email. Receiving mailbox providers evaluate the message separately. A correctly authenticated SMTP session does not automatically mean the visible From: domain has SPF, DKIM, and DMARC correctly configured.

Here are examples of the DNS syntax commonly used for a sending domain. They are illustrative, not copy-and-paste records for a specific provider:

; SPF: combine all legitimate senders into one TXT record
example.com. 3600 IN TXT "v=spf1 include:spf.email-provider.example ip4:198.51.100.42 -all"

; DKIM: selector and public key supplied by the sending service
mailer1._domainkey.example.com. 3600 IN TXT "v=DKIM1; k=rsa; p=BASE64_PUBLIC_KEY_MATERIAL"

; DMARC: begin with monitoring before enforcing a stricter policy
_dmarc.example.com. 3600 IN TXT "v=DMARC1; p=none; rua=mailto:dmarc-reports@example.com; adkim=r; aspf=r"

The SPF record authorizes listed sending sources for SPF evaluation; it is not a place to paste an API key. A DKIM p= value is public key material and is intended to be public. It is not the DKIM private signing key. Keep DKIM private keys, API keys, SMTP passwords, webhook signing secrets, and OAuth client secrets out of DNS.

Before changing live DNS, verify the exact hostnames and values supplied by your sender. Use dig TXT example.com, dig TXT mailer1._domainkey.example.com, or a DNS lookup tool such as MXToolbox to confirm that public records resolve as intended. Send a controlled test message to a mailbox you can inspect, then use message headers and a deliverability tool such as mail-tester.com to examine authentication results and content signals.

Rotate keys without breaking email delivery

Key rotation replaces a credential on a defined schedule or immediately after a risk event. Rotation limits the useful lifetime of a leaked secret and gives you practice performing a sensitive change under controlled conditions.

There is no universal rotation interval. The right schedule depends on key scope, provider features, production change maturity, personnel changes, regulatory obligations, and your ability to rotate safely. A highly privileged administrative credential should usually receive more scrutiny than a tightly scoped runtime sender key. More important than choosing a fashionable number of days is having a repeatable procedure that works during an emergency.

Use overlapping credentials when possible

The safest rotation pattern is create, deploy, verify, revoke:

1. Create a new key with the same or narrower required permissions.
2. Store it as a new version in the secret manager.
3. Deploy or reload the application so it starts using the new value.
4. Verify successful sends, expected provider responses, event ingestion, and absence of authentication errors.
5. Monitor for a defined overlap period.
6. Revoke the old key.
7. Record the rotation, owner, reason, and old-key retirement time.

Do not revoke first and hope the replacement deployment succeeds. That approach turns a routine security task into an avoidable outage. For critical transactional email, use a short but deliberate overlap: long enough to prove all consumers moved, short enough to limit exposure from the old key.

Design deployments for secret changes

Some applications read environment variables only at process start. Others cache secrets at startup, while some can refresh credentials dynamically. Know which behavior your services have before rotating a production key.

For a stateless service, a rolling deployment can replace instances gradually. For a queue worker fleet, drain or restart workers in batches and observe send success rates. For scheduled jobs, identify jobs that run infrequently; a monthly report worker can otherwise keep an old key alive undetected until the next month.

A rotation runbook should specify:

• The secret name and every consuming workload.
• The required provider permission scope.
• The deployment or reload procedure for each workload.
• A test recipient and expected message result.
• The expected normal HTTP or SMTP responses.
• Dashboard queries or logs used to verify adoption.
• The rollback plan if the new key fails.
• The exact point at which the old key may be revoked.

Rotate immediately after a suspected exposure

Routine rotation is not an excuse to wait after a leak. If a key appears in a public repository, CI log, support ticket, chat transcript, browser bundle, compromised workstation, or unfamiliar system, assume it is compromised.

Create a new key, deploy it, and revoke the exposed key as quickly as your service dependency permits. Then investigate the exposure path and usage history. A key can be copied before a repository is made private again or before an old commit is rewritten, so remediation must invalidate the credential rather than merely hide the text.

Detect leaks before they become incidents

Prevention should exist at several layers because no one control catches every mistake. Developers need a safe local workflow, repositories need scanning, CI needs policy checks, and operations teams need alerting on abnormal usage.

Scan commits, branches, and artifacts

Use pre-commit secret scanners and repository-level scanning. Tools such as Gitleaks, TruffleHog, GitHub secret scanning, and push protection can detect many credential patterns before or after they reach a repository. Push protection is particularly useful because it can block supported secrets before they are pushed rather than merely alerting after exposure.

Scanning must cover more than the default branch. Check full Git history, pull-request refs, tags, release assets, build logs, container image layers, infrastructure repositories, documentation repositories, sample projects, and generated configuration files.

A simple local policy can catch obvious problems:

Reject commits containing likely credentials in:
- .env files other than .env.example
- application source files
- YAML deployment manifests
- JSON configuration exports
- shell history or debug output
- test fixtures and snapshot files

Pattern detection has limits. A scanner may miss an unknown token format, an encoded secret, a screenshot, or a credential stored in an external paste. It can also flag harmless values. Treat it as a guardrail, not permission to relax code review and access controls.

Monitor usage as a security signal

Track sending volume, API errors, authenticated source IPs where available, endpoint usage, sender domains, recipient geography where appropriate, bounce rates, and unusual time-of-day patterns. A compromised credential may show up as a surge in sends, failed calls from a new environment, unexpected sender identities, or a sudden spike in recipient rejections.

Set alerts that are actionable. For example:

• More than three authentication failures per minute from a production worker pool.
• Any send attempt using a retired key identifier.
• A large volume increase above the service’s normal baseline.
• New sender domains or unauthorized From: addresses.
• A sudden rise in 429 Too Many Requests, 5xx, bounce, complaint, or suppression-related events.

Email security and deliverability overlap here. Unauthorized mail can harm your account reputation, domain reputation, customer trust, and legitimate message placement. Investigate both the access-control event and the downstream email impact.

Troubleshoot authentication failures without exposing secrets

When mail stops sending, do not paste a full API key into a ticket or share a screenshot of a request header. Diagnose the failure using key labels, timestamps, request IDs, sanitized configuration checks, and status codes.

HTTP status codes to recognize

Providers can add their own error formats, but standard HTTP classes give useful first direction:

• 400 Bad Request: the server could not process the request as sent. Check malformed JSON, required fields, invalid email addresses, or headers.
• 401 Unauthorized: authentication is missing, invalid, expired, revoked, or formatted incorrectly. Verify the header scheme and secret injection without logging the secret.
• 403 Forbidden: the credential may be valid but lacks permission, the sender/domain is not approved, or an account policy blocks the action.
• 404 Not Found: commonly an incorrect path, API version, hostname, or region; do not assume it means the key is wrong.
• 409 Conflict: may indicate a duplicate or conflicting request, depending on the API.
• 422 Unprocessable Content: the request syntax is valid but a field fails provider validation.
• 429 Too Many Requests: rate limit or quota protection. Respect any Retry-After header and apply bounded backoff.
• 500, 502, 503, or 504: service-side or network-path failures. Retry only when the operation is safe to retry and idempotency is addressed.

A 401 and a 403 are not interchangeable. A 401 should lead you to credential existence, format, and revocation state. A 403 should lead you to scopes, sender authorization, account state, domain verification, and policy restrictions.

SMTP responses to recognize

SMTP uses three-digit reply codes. The exact text varies by server, but the first digit conveys the broad result:

• 2xx: success, such as 250 for a command accepted.
• 4xx: temporary failure, such as 421 service unavailable or 450 mailbox temporarily unavailable. Retry with backoff when appropriate.
• 5xx: permanent failure, such as 535 authentication credentials invalid or 550 mailbox unavailable or rejected.

For SMTP authentication failures, verify the host, port, TLS mode, username, password or key, and authentication mechanism against the provider documentation. Do not solve a 535 by switching off TLS verification or by embedding a production password in a test script.

For delivery failures after authentication, capture the enhanced status code and server response. A 550 5.1.1 often indicates an invalid or unavailable recipient mailbox, while 5.7.x responses commonly point to policy, authorization, or security concerns. Interpret the complete provider and receiving-server response rather than relying on the first three digits alone.

Make retries deliberate

Do not retry authentication errors automatically forever. Retrying a 401, 403, or SMTP 535 with the same bad credential increases noise and may trigger security controls. Alert an owner and stop or slow the failing workload.

For temporary network failures, 429, many 5xx responses, and appropriate SMTP 4xx responses, use exponential backoff with jitter and a maximum attempt count. Separate retryable transport failures from permanent content or recipient failures. If you retry a send after an ambiguous timeout, use an idempotency mechanism or your own message identifier to avoid duplicate mail.

Build an incident response plan for exposed keys

A credential incident needs a prepared sequence. Under pressure, teams often focus on removing a leaked string from a repository and forget to stop the credential from working. Revocation and containment come first.

First-hour response checklist

1. Contain: disable or revoke the exposed key, or restrict it immediately if a safe replacement cannot be deployed instantly.
2. Replace: create a new scoped credential and update every confirmed consumer through the secret manager and normal deployment path.
3. Validate: send controlled test messages and inspect API, SMTP, webhook, and queue-worker health.
4. Investigate: review provider activity, application logs, repository events, CI logs, access records, sender identity changes, and unusual email volume.
5. Preserve evidence: retain relevant request IDs, timestamps, key identifiers, audit events, and sanitized logs.
6. Remediate the source: remove the secret from current files, restrict access to affected artifacts, and address the workflow failure that caused the exposure.
7. Communicate: notify the service owner, security team, and affected stakeholders using your incident process.

If unauthorized sending occurred, examine whether recipients received phishing, spam, or sensitive data. Check for changes to templates, sender identities, webhooks, suppression lists, account users, or forwarding rules if the provider account makes those actions possible. The blast radius is determined by the key’s permissions and the attacker’s observed activity—not by what you think they probably did.

Learn from the incident

After service restoration, run a blameless review. Ask why the credential was available in the place it leaked, why automated controls did or did not catch it, how quickly it was revoked, and whether the system had enough separation to rotate without outage.

Common durable improvements include moving secrets into a managed store, adding repository scanning, narrowing key scopes, eliminating shared credentials, creating a test-only sending path, adding outbound network restrictions, and rehearsing rotation. The objective is to change the system so the same class of mistake is less likely and less damaging.

A practical baseline for transactional email teams

A small team does not need a complex enterprise vault program on day one, but it does need a baseline that is stronger than putting one permanent key in a .env file and hoping nobody commits it.

Use this baseline as a starting point:

• Create separate credentials for production, staging, and local development.
• Give each production service its own send-only key where provider features allow it.
• Store production credentials in a managed secret store, not in source control.
• Inject secrets at runtime and redact them from logs, errors, traces, and support exports.
• Keep keys server-side; browser and mobile clients should use your backend.
• Enable secret scanning and a pre-commit or CI check for source repositories.
• Maintain an owner, workload, scope, creation date, and rotation record for every key.
• Test key rotation using overlapping credentials before an incident forces you to do it.
• Monitor volume, authentication failures, source changes, and unusual sending behavior.
• Configure SPF, DKIM, and DMARC separately from API credentials, then verify email headers and DNS records.

As sending volume and team size grow, add stricter scopes, short-lived workload identity where the platform supports it, IP or network restrictions, dedicated incident drills, policy-as-code, and segregated credentials for different message classes. Password resets, receipts, account alerts, and bulk notifications do not necessarily deserve the same permissions or risk tolerance.

The second-order impact: reliability and deliverability

API key management is often framed exclusively as security, but it is also a reliability practice. A credential rotation that is not rehearsed can stop password-reset emails. A key embedded in a build image can be difficult to replace quickly. An over-broad key used by several services makes it impossible to identify which workload caused a sending spike.

It also influences deliverability. If an attacker uses your credentials to send abusive messages, mailbox providers may see unwanted traffic associated with your authenticated infrastructure or sending domain. Even after the key is revoked, legitimate mail may suffer from damaged reputation, increased complaints, or recipient distrust.

The most resilient setup has layers: private runtime credentials, verified sending domains, provider-side permissions, application-level authorization, rate controls, accurate event monitoring, and tested incident response. None of these mechanisms is a substitute for the others. Together, they make it harder for a secret leak to become a customer-facing email failure.

Conclusion

Good API key management means treating email credentials as production identities: give each one a narrow purpose, store it outside code, never expose it to clients, monitor its use, rotate it through a tested overlap process, and revoke it immediately when exposure is suspected.

For transactional email, also keep the distinction clear between service access and domain trust. An API key or SMTP password lets your application submit mail; SPF, DKIM, and DMARC help receiving systems evaluate whether that mail is genuinely authorized by your domain. Secure both layers, log safely, and practice the recovery path before you need it.

FAQ

How often should API keys be rotated?

There is no single correct interval. Rotate according to the credential’s privilege, exposure risk, provider capabilities, and your operational ability to deploy safely. Always rotate immediately after suspected exposure, and use overlapping keys so routine rotation does not interrupt sending.

Is an API key safe in an environment variable?

It can be acceptable as a runtime injection method, but an environment variable is not a complete secret-management solution. Use a managed secret store, restrict who and what can read the secret, avoid logging process environments, and restart or reload workloads safely when the value changes.

Can I put a transactional email API key in a frontend app?

No. Any key shipped to a browser, mobile app, or public client can be extracted and abused. Put the email-provider credential on your backend and expose only a controlled application endpoint to clients.

What is the difference between an API key and SPF, DKIM, or DMARC?

An API key authenticates your application to an email service. SPF, DKIM, and DMARC are public DNS-based email authentication mechanisms that receiving mail systems use to evaluate messages. They solve different problems and should be configured separately.

What should I do if an API key is committed to Git?

Assume it is compromised. Create and deploy a replacement key, revoke the exposed key, review usage and logs, remove the secret from current files and history where appropriate, and add scanning or push protection so future commits are blocked earlier.