Authentication

Making an authenticated request

Include your API key in every request using the X-XRNotify-Key header. The key is passed as a plain string. No encoding or prefix is required.

curl https://api.xrnotify.io/v1/webhooks \
  -H "X-XRNotify-Key: xrn_live_your_key_here"

Node.js

const response = await fetch("https://api.xrnotify.io/v1/webhooks", {
  headers: {
    "X-XRNotify-Key": process.env.XRNOTIFY_API_KEY,
  },
});
const data = await response.json();

Python

import os, requests

response = requests.get(
    "https://api.xrnotify.io/v1/webhooks",
    headers={"X-XRNotify-Key": os.environ["XRNOTIFY_API_KEY"]},
)
data = response.json()

Security best practices

• ✓Store API keys in environment variables or a secrets manager. Never hard-code them.
• ✓Use the principle of least privilege. Only grant the scopes each key actually needs.
• ✓Set expiration dates on keys used in CI/CD pipelines or temporary environments.
• ✓Rotate keys periodically and revoke any key that may have been exposed.
• ✓Use separate keys for production and development. Never share keys across environments.
• ✓Monitor the "Last Used" timestamp on the API Keys dashboard to detect unauthorized usage.

API key types

XRNotify provides two key types. The prefix tells you which environment the key belongs to.

Creating API keys

Via dashboard

Navigate to Settings → API Keys → Create Key. Give it a name, select the scopes you need, and optionally set an expiration date. The key is shown once on creation. Copy it before closing the dialog.

Via API

You can create keys programmatically using an existing admin-scoped key:

curl -X POST https://api.xrnotify.io/v1/api-keys \
  -H "X-XRNotify-Key: xrn_live_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Bot",
    "scopes": ["webhooks:read", "webhooks:write"],
    "expires_at": "2025-12-31T23:59:59Z"
  }'

Available scopes

Rate limits

Rate limits are applied per API key. Limits vary by plan:

Rate limit headers

Every API response includes these headers so you can track usage:

Authentication errors

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key. Pass your key in the X-XRNotify-Key header."
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "This key does not have the required scope: webhooks:write"
  }
}

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 2026-04-15T10:24:00Z."
  }
}
// Response also includes: Retry-After: 15