Every request to the Sozuri API is authenticated with a project name and an API key. Both are required, and they must belong to the same project: the project tells us which sender IDs, balance and callback to use; the API key proves the request is yours.

Your project

A project is your workspace inside Sozuri. Each project has its own sender IDs, callback URL, 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 name (for example Galaxion Marketing), not its id. You’ll find it on the project dashboard.

Your API key

Every project has an API key from the moment it is created. Open Manage API › API Credentials on the project dashboard to view it; the page is available to the project owner and project admins. Treat the key like a password — anyone who has it, and your project name, can send messages and spend your balance.

Including credentials in a request

Send the API key in one of two ways, and always send project as well:

• As a Bearer token — an Authorization: Bearer <key> header (recommended).
• As an apiKey field — in the query string, a JSON body or a form-encoded body.

project goes in the query string or the body, alongside your other fields. There is no header for the key other than Authorization: a key sent in a header named apiKey is not read, and the request is refused with 401.

GET requests

Pass both as query parameters (URL-encode the project name):

GET /api/v1/messaging?project=Your%20Project%20Name&apiKey=YOUR_API_KEY&...

POST requests (JSON body)

Use a Bearer token header for the key and put project in the JSON body — or put both in the body:

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

{
    "project": "Your Project Name",
    "from": "MySenderID",
    "to": "254700000001",
    "message": "Hello from Sozuri",
    "type": "transactional"
}

POST requests (form-encoded body)

Include them alongside your other form fields:

project=Your%20Project%20Name&apiKey=YOUR_API_KEY&from=MySenderID&to=254700000001&message=Hello&type=transactional

Check your credentials

GET https://sozuri.net/api/v1/messaging/authtest tells you whether a project name and API key are accepted. It sends nothing, charges nothing and changes nothing, so it is safe to call whenever you set up or rotate a key. Authenticate it exactly like any other request; it takes no other fields.

curl -G https://sozuri.net/api/v1/messaging/authtest \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Accept: application/json' \
    --data-urlencode 'project=Your Project Name'

With the key in the query string instead:

GET /api/v1/messaging/authtest?project=Your%20Project%20Name&apiKey=YOUR_API_KEY

When the credentials are accepted, the answer is HTTP 200:

{
    "messageData": {
        "message": "Success. Project found."
    }
}

When they are not, it is the 401 described below.

Auth error responses

Every endpoint that takes an API key answers a request it cannot authenticate the same way: HTTP 401, before anything else in the request is looked at.

{
    "error_code": "AUTHENTICATION_FAILED",
    "message": "Authentication failed. Check your API key or bearer token.",
    "retryable": false
}