Skip to main content

Provider credentials

Nerve uses a Bring-Your-Own (BYO) credentials model. You open accounts directly with your chosen delivery providers, and Nerve orchestrates delivery, failover, rate limiting, and regulatory compliance.

Supported providers​

Nerve natively integrates eight leading delivery providers across four channels:

ChannelSupported ProvidersCommon Use Case
SMSTermii, Sendchamp, InfobipNigerian carrier delivery, DND routing, OTPs
EmailPostmark, SendGridHigh-reputation transactional & bulk email
PushFirebase Cloud Messaging (FCM), Apple Push Notification service (APNs)Android and iOS device notifications
WhatsAppMeta WhatsApp Cloud APIOfficial WhatsApp Business messaging

Envelope encryption architecture​

Provider credentials contain sensitive API secrets, service account JSONs, and Apple private keys (.p8). Nerve guarantees that no plaintext provider secret is ever stored in the database or exposed via any read API.

  1. Per-Record DEK: When a provider is saved, Nerve generates a cryptographically random 32-byte Data Encryption Key (DEK).
  2. Payload Encryption: The credential payload is encrypted using AES-256-GCM with a unique 12-byte random initialization vector (IV) and authenticated tag.
  3. Key Wrapping (KEK): The DEK is wrapped under the platform Key Encryption Key (KEK_V1) using AES-256-GCM.
  4. Database Storage: The database stores only ciphertext, nonce, wrapped_dek, kek_version, and a masked_hint.
  5. Zero Plaintext Reads: Read endpoints (GET /console/providers) return only the masked_hint (e.g., sk_live_...4f2a). Plaintext credentials cannot be queried back.

Connection testing​

Before routing production traffic to a newly added provider, test the connection:

curl -X POST https://console.nervly.io/console/providers/{providerId}/test \
  -H "Cookie: nerve_session=$SESSION_COOKIE" \
  -H "X-CSRF-Token: $CSRF_TOKEN"

The control plane performs an authentic, zero-delivery API verification call:

  • Termii: Queries account balance endpoint.
  • SendGrid: Queries API key scopes (/v3/scopes).
  • Postmark: Queries server configuration (/server).
  • Sendchamp: Queries wallet balance.
  • Infobip: Validates account status.
  • FCM / APNs: Generates RS256/ES256 signed JWTs and verifies key format.
  • Meta WhatsApp: Queries app details (/me).

On success, verified_at is updated in the database and logged to the workspace audit log.

Priority and failover order​

Each provider in a workspace has a numeric priority attribute (1 = primary, 2 = secondary fallback, 3 = tertiary fallback).

When dispatching an event:

  1. The Go worker retrieves enabled providers for the channel, sorted by priority ASC.
  2. The worker attempts dispatch against the primary provider.
  3. If the primary fails or its circuit breaker is open, the worker immediately falls back to the next priority provider.
  4. If all providers fail, the message is queued for exponential backoff retry and published to the Dead-Letter Queue (DLQ).

Next​