# Authentication



> Every protected `v1` request is authorized through a workspace-scoped API key. This page covers the required header shape, workspace scoping behavior, and authentication failure handling.



- Human page: https://mailrith.com/developers/authentication

- Markdown page: https://mailrith.com/developers/authentication.md

- Category: Getting Started

- Reading time: 5 min read

- Last updated: 2026-07-13

- Related keywords: Authentication, Authentication developer docs, Getting Started, Getting Started developer docs, Mailrith developer docs, Mailrith public API, Use Bearer Authentication, Understand Workspace Scope, Discover OAuth Metadata, Handle Authentication Failures, Quickstart, Testing the API, Errors



## AI Agent Notes

- Use this page as implementation guidance, then validate exact endpoint fields against the OpenAPI document.

- Keep API keys server-side and workspace-scoped unless a guide explicitly says otherwise.

- Do not invent privacy, consent, or lawful-basis evidence. Send only fields that appear in the OpenAPI schema for the endpoint you are using.



## What this guide covers

Use workspace-scoped Bearer keys and learn how Mailrith authorizes protected requests.



## Use Bearer Authentication

Every protected Mailrith API request uses Bearer authentication. Send the credential in the standard `Authorization` header. Do not send the credential in a query string, form field, custom header, or request body.

Use workspace API keys for direct server-to-server integrations. Use OAuth access tokens only when Mailrith has approved your integration to use delegated authorization and a user has explicitly connected the integration.

Never send Mailrith credentials from browser JavaScript or mobile app code that users can inspect. Keep API keys and OAuth client secrets on a trusted server.

1. Load the API key or OAuth access token from a server-side secret store.
2. Attach the credential to every protected request as `Authorization: Bearer <credential>`.
3. Send JSON requests with `Content-Type: application/json` when the endpoint expects a body.
4. Handle `401` responses as credential problems. Use the guidance in [Errors](https://mailrith.com/developers/errors.md) before you retry the request.
5. Rotate or revoke workspace API keys from [API Keys and Authorized Apps](https://mailrith.com/docs/api-keys-and-authorized-apps.md) when a credential is exposed or no longer has a clear owner.

**Request Headers**

```http
Authorization: Bearer mrk_example_secret_key
Content-Type: application/json
```

## Understand Workspace Scope

A workspace API key always belongs to one workspace. The key controls which subscribers, tags, forms, landing pages, broadcasts, sequences, automations, and jobs the request can access.

Do not pass a `workspace_id` in public `/v1` requests. The credential already selects the workspace. This prevents an integration from accidentally writing data into a different workspace because it sent the wrong ID.

If you manage several client or brand workspaces, create a separate key for each workspace. Keep the keys in separate environment variables or secret records so the integration cannot mix subscribers from different workspaces by mistake.

## Discover OAuth Metadata

Approved OAuth clients should start from `/.well-known/oauth-authorization-server`. The discovery response tells the client where to send users for authorization, where to exchange authorization codes for tokens, and where to revoke tokens later.

OAuth is for delegated integrations where a user connects Mailrith to another product. A workspace API key is usually simpler for backend jobs that your own team controls.

Build OAuth clients against the discovery document instead of hard-coding endpoint paths. This makes the integration easier to maintain if the authorization server metadata grows over time.

**Authorization Server Metadata**

```bash
curl https://api.mailrith.com/.well-known/oauth-authorization-server
```

## Handle Authentication Failures

If the credential is missing, malformed, expired, revoked, or unknown, Mailrith returns `401` with a stable error envelope. Treat this response as an access problem, not as a temporary server failure.

Do not retry `invalid_api_key` in a tight loop. The same bad key will keep failing. Alert the integration owner, replace or rotate the credential, and then retry with the new credential.

When an integration suddenly starts receiving `401`, check the credential. Confirm that the key was not revoked, was copied correctly, has no extra whitespace, is attached to the correct environment, and was created for the expected workspace.

**Authentication Error**

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "A valid workspace API key is required."
  }
}
```



## Related Guides

- [Quickstart](https://mailrith.com/developers/quickstart.md): Start with one workspace API key, one authenticated request, and the generated response envelope. This page covers the minimum steps needed to create a working subscriber sync.

- [Testing the API](https://mailrith.com/developers/testing-the-api.md): You can test Mailrith's public API manually with local curl requests or automatically with the integration suite. This page shows the repo-native commands for both testing paths.

- [Errors](https://mailrith.com/developers/errors.md): Non-2xx responses include stable error codes and plain-language messages. This guide explains how to log errors, avoid matching on message text, map status codes to user or system actions, and retry only when the same request may succeed later.