AUTHENTICATION

How authentication works (token-based)

Every v3 API request must include an `Authorization: Bearer <token>` header. Tokens are tenant-scoped — a token can only act on resources belonging to the tenant that created it. ## 1. Create a token Log in to your dashboard, open **Settings → API Keys**, click **Create token**, and copy the token value (shown only once). Tokens have an optional expiry; if omitted, they don't expire. ## 2. Make your first request Use the token in the `Authorization` header. Verify it works by hitting `GET /api/v3/me`: ```bash curl https://pulse.momo.tz/api/v3/me \ -H 'Authorization: Bearer YOUR_TOKEN' ``` ## 3. Token scopes All v3 tokens have full read/write access on the tenant's resources today. Per-endpoint scoping is on the roadmap; in the meantime, treat tokens as full credentials and rotate them if leaked. ## 4. Rate limiting - SMS / WhatsApp send: **60 req/min** per tenant - Read endpoints: **120 req/min** - Campaign creation: **10 req/min** Responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` headers. A `429` means you've hit the cap — back off and retry after the reset. ## 5. Error handling All errors follow the envelope `{ "status": "error", "message": "...", "errors": { ... } }`. Validation errors come back as `422` with `errors` keyed by field name.