# 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-28 - 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, Add Missing Permissions, 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 `. 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. Send exactly one `resource` parameter at authorization, code exchange, and refresh. Use `https://api.mailrith.com/v1` for the public API or `https://api.mailrith.com/mcp` for the MCP server. Request the smallest required `scope` set. Put permissions the user can safely remove in `optional_scope`. Mailrith binds the code and both token types to the selected resource and rejects a token at the other resource. **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." } } ``` ## Add Missing Permissions Mailrith never silently adds permissions to an existing credential. If an app receives `insufficient_scope`, read `credential_type`, `missing_scopes`, `replacement_scopes`, and `recovery` from the error response before asking the user to take action. For OAuth, the connected app must start authorization again because it owns the secure callback state. Keep the current connection in place while the new authorization runs so existing workflows can continue using their current access. For a workspace API key, create a replacement key with every permission in `replacement_scopes`, replace the saved key in the calling app, confirm the new key works, and then revoke the old key. This preserves permissions the integration already uses while adding only what is missing. 1. Read `credential_type`, `missing_scopes`, `replacement_scopes`, and `recovery.action` from the `403 insufficient_scope` response. 2. If `recovery.action` is `reconnect_oauth`, add the missing permissions to the app's next OAuth request and ask the user to reconnect Mailrith from that app. 3. If `recovery.action` is `replace_api_key`, open Settings, choose API Keys, select Create API Key, and include every permission in `replacement_scopes`. 4. Replace the old token or key in the calling app. 5. Confirm the replacement API key can complete the original operation. Then return to Settings, choose API Keys, open the old key's Actions menu, and select Revoke. 6. Retry the original operation with the replacement credential. ## 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.