# Authentication

# Authentication

Use a scoped API key for server integrations. Sign in to the hosted application to manage your account, API keys, security settings, and billing.

## API keys

Create a key in **Settings** and grant only the scopes your integration needs. The plaintext key is shown once. Store it in a secret manager and keep it out of browser code, URLs, logs, and shared examples.

```bash
curl --fail-with-body "https://wildmail.app/api/messages" \
  -H "Authorization: Bearer $WILDMAIL_API_KEY"
```

A key accesses resources in the account where it was created. A missing or invalid key returns **401**. A valid key without the required scope returns **403**. When an `Authorization` header is present, it takes precedence over browser session cookies, even if the key is invalid. Revoke a key in **Settings** to stop future requests using it.

Account settings, account deletion, key management, and billing require a signed-in browser session. API keys cannot perform those actions. See the [API reference](https://docs.wildmail.app/docs/api/reference.md) for each operation's required scope and authentication method.

## Sign in to your account

Email-code sign-in is the default option. Enter your email, request a six-digit code, and use it within five minutes. Each code works once and allows three verification attempts. Requesting a new code replaces the previous one. Password sign-in is also available. Registration is available only when enabled for the hosted service.

If you have enabled two-factor authentication, email-code and password sign-in also require your authenticator, security key, or recovery code. A sign-in email code is the first step and does not replace your second factor. Google and GitHub sign-in use the provider's authentication, so protect those accounts with the provider's security controls.

Use **Settings** to enroll and manage authenticators, security keys, and recovery codes. Sign in with email first to manage these settings. Save recovery codes when they are shown. Replacing them invalidates the previous set. Password reset links are single-use and expire after one hour. Completing a reset signs out existing sessions and preserves second-factor settings.

For more account-security behavior, see [Integration and account security](https://docs.wildmail.app/docs/guides/security.md).

## Webhook signatures

A Wildmail API key authenticates requests from your application to Wildmail. An endpoint's signing secret lets your receiver authenticate incoming webhook requests. They are separate credentials and rotate independently.

Follow [Verify and consume webhooks](https://docs.wildmail.app/docs/guides/webhooks.md) to validate signatures against the exact request bytes and deduplicate retries by event ID.
