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.

5 min read

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.

Load the API key or OAuth access token from a server-side secret store.
Attach the credential to every protected request as Authorization: Bearer <credential>.
Send JSON requests with Content-Type: application/json when the endpoint expects a body.
Handle 401 responses as credential problems. Use the guidance in Errors before you retry the request.
Rotate or revoke workspace API keys from API Keys and Authorized Apps when a credential is exposed or no longer has a clear owner.

Request Headers

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

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

{
  "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

Quickstart

Testing the API