API Reference

Authentication

All XRNotify API requests must be authenticated using an API key passed in the X-XRNotify-Key request header.

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"

Keep keys secret: Never expose API keys in client-side code, public repositories, or logs. Treat them like passwords. If a key is compromised, revoke it immediately from the dashboard.

API key types

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

Prefix	Environment	Use for
`xrn_live_`	Production	Real XRPL mainnet events, live webhook deliveries
`xrn_test_`	Test	Safe testing environment. No real events or charges.

Use test keys (xrn_test_...) during development and CI. They behave identically to live keys for all API operations but only deliver synthetic test events.

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

webhooks:read

List and retrieve webhook configurations

webhooks:write

Create, update, delete, and rotate webhook secrets

deliveries:read

View delivery history and details

deliveries:write

Retry failed deliveries

events:read

Query the event log

api_keys:read

List API keys

api_keys:write

Create and revoke API keys

admin

Full access to all endpoints and resources

Rate limits

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

Plan	Requests / min	Requests / day
Free	60	1,000
Starter	300	10,000
Pro	1,000	100,000
Enterprise	Custom	Custom

Rate limit headers

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

X-RateLimit-Limit

Maximum requests allowed in the current window

X-RateLimit-Remaining

Number of requests remaining in the current window

X-RateLimit-Reset

Unix timestamp when the rate limit window resets

Authentication errors

401 UnauthorizedMissing or invalid API key

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

403 ForbiddenValid key but missing required scope

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

429 Too Many RequestsRate limit exceeded

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

Next steps

Webhooks API

Create and manage webhooks

Deliveries API

Monitor event delivery status

Events API

Query the XRPL event log