Concepts

Authentication

Two ways to authenticate — API keys for services, our auth service bearer tokens for humans. Same backend, different headers.

Two modes

Every request to Nudgel is authenticated. Pick based on who's making the call:

Caller	Use	Endpoints
Your back-end service	API key (`X-Raven-Key`)	`/v1/messages`, `/v1/contacts`, etc.
A signed-in human (dashboard)	Bearer token (our auth service)	`/v1/admin/*`

API key auth

Pass the API key as the X-Raven-Key header. The tenant is implied by the key — no other auth headers required.

bash

curl https://api-raven-cloud.autotribes.app/v1/messages \
  -H "X-Raven-Key: rk_live_a3f7b2c1_..." \
  -H "Content-Type: application/json" \
  -d '{"channel":"sms","to":"+254722000000","template":"otp"}'

sign-in session auth

For the admin endpoints (/v1/admin/*) we accept an a sign-in session token, plus a tenant scope:

bash

curl https://api-raven-cloud.autotribes.app/v1/admin/api-keys \
  -H "Authorization: Bearer eyJ..." \
  -H "X-App-Name: raven-cloud" \
  -H "X-Tenant-Slug: acme-co"

The token is an HS256-signed JWT. Nudgel verifies it locally with the shared JWT_SECRET — no network round-trip per request.

Why our auth service (and not us)

DELEGATED IAM

We don't want to be in the password-reset business. our auth service (the our platform sign-on) handles sign-in, MFA, and Google OAuth across every product in the ecosystem. One identity per human, reused across Nudgel, TribeFest and InstaEscrow, and the rest. We just store which tenants you belong to.