AuthenticationCopy Anchor Link

Most NorthRelay API requests require authentication; tracking and signed unsubscribe endpoints have separate public access rules. The primary API method is Bearer authentication using API keys. Inactive, revoked and expired keys are rejected. Use the narrowest scope supported by the endpoint and rotate keys after exposure.

API keys require an active, verified account and grant access to that account's supported tenant APIs. Administrative actions require a dashboard session with recent MFA; an administrator's personal API key does not grant administrative privileges. Signing out revokes the dashboard session, and password/security changes require a fresh sign-in.

API Key FormatsCopy Anchor Link

NorthRelay issues two types of API keys, distinguished by prefix:

Both prefixes use the same validator. A prefix alone does not prevent real delivery or quota consumption. Use an isolated test environment and a mail sink for integration tests.

Creating an API KeyCopy Anchor Link

1. Navigate to Dashboard > Settings > API Keys
2. Click Create API Key
3. Enter a descriptive name (e.g., "Production Backend", "Staging CI")
4. Select the key scope (see Key Scopes below)
5. Click Generate
6. Copy the key immediately -- it is shown only once

The key is a long random string prefixed with nr_live_ or nr_test_:

nr_live_sk_7f3a9b2c4d5e6f1a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f

Using Your API KeyCopy Anchor Link

Include the key in the Authorization header as a Bearer token:

curl -X POST https://app.northrelay.ca/api/v1/emails/send \
  -H "Authorization: Bearer nr_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": { "email": "hello@yourdomain.com", "name": "Your App" },
    "to": [{ "email": "user@example.com" }],
    "content": {
      "subject": "Welcome!",
      "text": "Thanks for signing up."
    }
  }'

Node.js (fetch)Copy Anchor Link

const response = await fetch("https://app.northrelay.ca/api/v1/emails/send", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.NORTHRELAY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from: { email: "hello@yourdomain.com", name: "Your App" },
    to: [{ email: "user@example.com" }],
    content: {
      subject: "Welcome!",
      text: "Thanks for signing up.",
    },
  }),
});

const result = await response.json();

Python (requests)Copy Anchor Link

import os
import requests

response = requests.post(
    "https://app.northrelay.ca/api/v1/emails/send",
    headers={
        "Authorization": f"Bearer {os.environ['NORTHRELAY_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "from": {"email": "hello@yourdomain.com", "name": "Your App"},
        "to": [{"email": "user@example.com"}],
        "content": {
            "subject": "Welcome!",
            "text": "Thanks for signing up.",
        },
    },
)

result = response.json()

Key ScopesCopy Anchor Link

API keys can be scoped to limit their permissions:

Select the narrowest scopes that meet your use case. sending and read_only are not recognized scope names. The dashboard sending preset additionally includes template/domain read scopes. API key creation, deletion and revocation require full_access; keys:write alone cannot mint broader credentials. Unclassified routes require full_access by default. Existing legacy keys with null/empty stored scopes retain full access for compatibility and should be reviewed explicitly.

Keys Issued to Connectors (OAuth)Copy Anchor Link

An MCP client that speaks OAuth rather than taking a key — the claude.ai and Claude Desktop connectors — obtains one through the platform's authorization server (/.well-known/oauth-authorization-server). The client registers itself, sends you to a NorthRelay sign-in page that names the client and the address the token will go to, and you tick exactly the permissions it gets, starting from read-only. What is approved is an ordinary API key named oauth-<client>-…: it appears under Settings → API Keys, holds only the scopes you ticked (never full_access or keys:*), cannot authenticate to SMTP, expires after 30 days and is renewed by the client through a rotating refresh token. Revoking it under API Keys ends the connector's access: the next renewal is refused and the grant is closed. A refresh token presented twice, or an authorization code presented twice, revokes the whole grant — a stolen copy is indistinguishable from the real one until it is used twice, and which holder is the thief is unknowable.

Session AuthenticationCopy Anchor Link

New passwords and password resets require at least 12 characters, an uppercase letter, a lowercase letter and a digit, with a maximum of 72 UTF-8 bytes. Existing-account login remains compatible with previously accepted passwords.

Dashboard endpoints also accept NextAuth.js session cookies. This is used automatically when you interact with the API from the NorthRelay dashboard. Session auth is not recommended for server-to-server integrations -- use API keys instead.

Error ResponsesCopy Anchor Link

Authentication failures return a 401 status:

{
  "code": "UNAUTHORIZED",
  "message": "Authentication required",
  "action": "Sign in to your account or provide a valid API key.",
  "docs_url": "https://docs.northrelay.ca/api/authentication"
}

An invalid or revoked key returns:

{
  "code": "API_KEY_INVALID",
  "message": "The provided API key is invalid or has been revoked",
  "action": "Generate a new API key in Dashboard > Settings > API Keys.",
  "docs_url": "https://docs.northrelay.ca/api-keys/troubleshooting"
}

Usage and ActivityCopy Anchor Link

Every request made with a valid key is recorded against that key: the route (with ids collapsed to :id), the HTTP status, the client IP, the user agent and the duration. Requests refused for a missing scope are recorded too, with their 403, so a key calling a route it may not reach shows up where its owner will see it. SMTP logins with a user key are recorded as SMTP smtp/auth. Invalid or revoked keys cannot be attributed and leave no trace here.

Open Dashboard > Settings > API Keys and choose Activity on a key to see:

• requests, errors and the error rate over the last 7 or 30 days, with a daily chart;
• the busiest routes and the most recent calls, each with its status and origin;
• the key's lifecycle: created, permissions edited, secret rotated, revoked.

The key list shows the same totals per key with a sparkline, flags keys that expire within 14 days, and marks active keys older than 30 days that have never been used. History is kept for 90 days.

Security Best PracticesCopy Anchor Link

1. Never commit API keys to version control. Store them in environment variables or a secrets manager.

2. Use separate keys per environment. Create distinct keys for production, staging, and development.

3. Rotate keys regularly. Revoke and regenerate keys every 90 days or after any suspected exposure.

4. Use the narrowest scope. A backend that only sends emails should use a sending_access- or emails:send-scoped key.

5. Use nr_test_ keys for development. Avoid consuming production quota or accidentally sending real emails during testing.

6. Restrict server-side only. Never expose API keys in client-side JavaScript, mobile apps, or public repositories.

7. Monitor key usage. Review API key activity in Dashboard > Settings > API Keys to detect unauthorized use.

8. Revoke compromised keys immediately. If a key is leaked, revoke it in the dashboard and generate a replacement.