# Authentication



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



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

- Category: Getting Started

- Reading time: 5 min read



## What this guide covers

Use workspace-scoped Bearer keys and understand how protected requests are authorized.



## Use Bearer Authentication

Every protected Mailrith API request uses Bearer authentication. This means the credential is sent in the standard `Authorization` header and not 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 your integration has been approved to use delegated authorization and a user has explicitly connected it.

Never send Mailrith credentials from browser JavaScript or mobile app code where users can inspect them. 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 it 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 and use the guidance in [Errors](https://mailrith.com/developers/errors.md) before retrying.
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 owned.

**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 decides 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 workspace is already selected by the credential. This prevents an integration from accidentally writing data into a different workspace just because it sent the wrong ID.

If you manage several client or brand workspaces, create a separate key for each one. Keep the keys in separate environment variables or secret records so the integration cannot mix audiences 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 keeps 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 as an access problem, not as a temporary server failure.

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

When an integration suddenly starts receiving `401`, check whether the key was revoked, copied incorrectly, stored with extra whitespace, attached to the wrong environment, or created for a different workspace than expected.

**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 needed to go from zero to a working subscriber sync.

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

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