NotifyHub Admin API
Home · Docs · Admin API
Provisioning

Use the admin key to create and update platform data.

The admin API is for operators and automation. Clients should use their own API key only for sending notification requests.

Auth

Admin and read-only keys

Header Role Purpose
X-Notification-Admin-Token Admin Create, patch, disable, and manage platform records.
X-Notification-Read-Token Read-only Inspect records, routes, templates, and status without mutating data.
Security rule Do not place real tokens or provider secrets in docs or source control. The platform stores references, not raw secret values, wherever possible.
Clients

Onboard a client in three steps

1. Create the client

Use POST /v1/clients to create a client identity and return a client API key.

POST /v1/clients
X-Notification-Admin-Token: <admin token>
{
  "tenant_id": "tenant-a",
  "client_name": "billing-service",
  "allowed_channels": ["email", "sms", "whatsapp", "push", "webhook"],
  "enabled": true
}

2. Share the client API key with the service

The client API key is what upstream services use for POST /v1/notification-requests.

3. Constrain channel access

Allowed channels are enforced by the control plane before a request can be accepted.

Providers

Register provider accounts and secret references

A provider account stores public config and secret references separately. That lets you keep credentials in a secret manager or mounted secret file instead of embedding them in the request.

POST /v1/provider-accounts
X-Notification-Admin-Token: <admin token>
{
  "tenant_id": "tenant-a",
  "provider_key": "<provider_key>",
  "display_name": "Primary WhatsApp account",
  "channel": "whatsapp",
  "enabled": true,
  "config": {
    "username": "<provider_username>",
    "base_url": "<provider_base_url>"
  },
  "secret_refs": {
    "password": {
      "ref": "secret://tenant/tenant-a/providers/<provider_key>/password",
      "material_type": "secret_string"
    }
  }
}

Typical follow-up actions:

Patch provider account

PATCH /v1/provider-accounts/{providerAccountID} updates config, display name, enabled state, or secret references.

Disable provider account

POST /v1/provider-accounts/{providerAccountID}/disable stops the account from being selected by routing.

Policy

Configure routing, templates, preferences, and delivery behavior

Routing policies

Map an event name to the channels and binding set that should receive the event.

POST /v1/routing-policies
{
  "event_name": "<event_name>",
  "channels": ["sms", "whatsapp"],
  "binding_set": "<binding_set>",
  "enabled": true,
  "priority": 10
}

Templates

Templates are stored in the control plane and selected by template_key, channel, and language_code.

POST /v1/templates
{
  "template_key": "<template_key>",
  "channel": "whatsapp",
  "language_code": "en",
  "body_template": "{{otp}} is your verification code.",
  "enabled": true
}

Preference policies

Preference policies suppress channels that a user has opted out of before dispatch starts.

Delivery policies

Delivery policies set retries and backoff per channel, so provider-specific behavior stays declarative.

Callbacks

Register callback routes and webhook subscriptions

Callback routes are how providers return delivery status and inbound message events to the control plane. Webhook subscriptions are how downstream systems receive normalized lifecycle events from the control plane.

Callback routes

Use POST /v1/callback-routes to map a provider key to a provider callback path and verification mode.

Webhook subscriptions

Use POST /v1/webhook-subscriptions to forward normalized lifecycle events to another system.

POST /v1/callback-routes
{
  "provider_key": "<provider_key>",
  "provider_account_id": "<provider_account_id>",
  "callback_path": "/v1/providers/<provider_key>/<provider_account_id>/callbacks",
  "verification_mode": "shared_secret",
  "verification_secret_ref": {
    "ref": "secret://tenant/tenant-a/providers/<provider_key>/callback-secret",
    "material_type": "secret_string"
  },
  "enabled": true
}