Getting Started

Authentication

Every request to the Sozuri API is authenticated with a project name and an API key. The project tells us which sender ID, credits and callback to use; the API key proves the request is yours.

The base URL for all messaging endpoints is https://sozuri.net/api/v1/messaging.

Your project

A project is your workspace inside Sozuri. Each project has its own sender ID, callback URL, credit balance and API key — so you can keep development, staging and production isolated, or split traffic per app or per team.

The project parameter in your requests is the project’s display name (for example Galaxion Marketing). You’ll find it on the project dashboard.

Your API key

Once your project is created, open Manage API › API Credentials on the project dashboard to view its key. Treat the key like a password — anyone who has it can send messages and spend your credits.

Regenerating an API key immediately invalidates the previous one. If you lose your key you can always retrieve or regenerate it from Settings › API Credentials.

Including credentials in a request

Where you put the project and apiKey depends on the request type:

GET requests

Pass both as query parameters:

GET /api/v1/messaging?project=Your_Project_Name&apiKey=Your_API_Key&...
POST requests (JSON body)

Include them as fields in the JSON body, or use a Bearer token header for the key:

POST /api/v1/messaging HTTP/1.1
Host: sozuri.net
Content-Type: application/json
Authorization: Bearer Your_API_Key

{
    "project": "Your_Project_Name",
    "from": "Sozuri",
    "to": "254700000001",
    "message": "Hello from Sozuri"
}
POST requests (form-encoded body)

Include them alongside your other form fields:

project=Your_Project_Name&apiKey=Your_API_Key&to=254700000001&message=Hello
We recommend the Bearer token approach — it keeps the API key out of logs, browser history and analytics, and works for both GET and POST. See the full list of headers on the Request headers page.

Auth error responses

These authentication errors are shared by every messaging endpoint — SMS, WhatsApp, Premium and Airtime. The envelope follows the channel’s own pattern (messageData.message for SMS/WhatsApp/Premium, data.message for Airtime), so the string is the same but the wrapper differs.

ConditionHTTPResponse body
The project in the request doesn’t exist on Sozuri. 404 
{
    "messageData": { "message": "Error. Project not found." }
}
The project exists but the apiKey/Bearer token doesn’t match it — or the request couldn’t be resolved to a project. 400 
{
    "messageData": { "message": "Error. Unknown project." }
}
No apiKey or Bearer token provided at all. 401 
{ "message": "Unauthenticated." }
If you’re seeing Project not found. when the project clearly exists, double-check capitalisation and whitespace on the project field — it’s the project’s display name, not its id.

Use cases

How teams structure their Sozuri authentication in the real world.

Separate dev, staging & production

Create one project per environment. Each has its own API key and credit balance, so a buggy staging job can never spend production credits or hit real customers.

One project per app or team

Marketing, transactional and support traffic each get their own project. Easier reporting, cleaner sender IDs, and revoking a single key doesn’t disrupt the whole organisation.

Rotate keys on schedule

Regenerate the API key from the dashboard whenever an engineer leaves or a key is suspected leaked. The new key is active immediately — redeploy with the new value and you’re back online.

Authenticated. What next?

Head to Request headers for the full list of accepted headers, or jump straight to Send Bulk SMS.

Send your first SMS See request headers