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.

3 min read

Use Bearer authentication

Every request to the protected v1 surface uses a workspace-scoped bearer credential.

Use Authorization: Bearer <credential> on every protected request.

Workspace API keys remain available for direct integrations that manage their own secrets.

Approved OAuth clients can discover Mailrith's delegated authorization server at /.well-known/oauth-authorization-server.

OAuth discovery and token exchange endpoints are available for integrations that need delegated bearer credentials instead of long-lived API keys.

Mailrith accepts the public API token only through the standard Authorization header. The public surface does not support alternate header names.

Request headers

Authorization: Bearer mrk_example_secret_key
Content-Type: application/json

Understand workspace scope

Each API key maps to exactly one workspace. That means GET /v1/tags, GET /v1/forms, and the rest of the protected surface always operate against the workspace that issued the key.

You do not pass a workspace_id on public v1 requests. The key is the workspace selector.

Discover OAuth metadata

Approved OAuth clients should start from /.well-known/oauth-authorization-server to discover Mailrith's authorization, token, and revocation endpoints.

This discovery document is the stable configuration surface for delegated integrations. Direct API-key flows remain available for server-to-server use cases.

Authorization server metadata

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

Handle authentication failures

If the token is missing, malformed, or unknown, Mailrith returns 401 with a stable error envelope.

Treat invalid_api_key as non-retryable until you replace or rotate the credential.

Authentication error

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

Need help shipping an integration?

Reach the Mailrith team if you need help planning a sync, validating a webhook flow, or troubleshooting a request.

Contact Mailrith

Related guides

4 min read

Quickstart

Create a workspace key and make the first authenticated request against Mailrith's public API.

5 min read

Testing the API

Run the local worker, generate a workspace key, exercise the endpoints, and execute automated integration coverage.

3 min read

Errors

Handle stable error envelopes and status codes without depending on internal implementation details.

Quickstart

Testing the API