An organization is the root container for your business on Nyota Imara. Every team member, billing subscription, order, and delivery is scoped to an organization. This guide walks you through creating one and making your first organization-scoped API calls.
Create your organization
Send a POST request to /v1/organizations. Only name and slug are required; all other fields are optional but recommended for KYB and billing purposes.
Send the create request
curl -X POST https://api.nyotaimara.com/v1/organizations \
-H "Authorization: Bearer <your_token>" \
-H "Content-Type: application/json" \
-d '{
"name": "Savanna Supplies Ltd",
"slug": "savanna-supplies",
"kraPin": "A001234567X",
"billingEmail": "finance@savanasupplies.co.ke",
"address": "14 Mombasa Road",
"city": "Nairobi",
"country": "Kenya"
}'
Receive the organization record
A 201 Created response returns the new organization object:{
"success": true,
"data": {
"id": "org_01j9kxp8a3bvc0nqrtzwmde4fy",
"name": "Savanna Supplies Ltd",
"slug": "savanna-supplies",
"kraPin": "A001234567X",
"billingEmail": "finance@savanasupplies.co.ke",
"address": "14 Mombasa Road",
"city": "Nairobi",
"country": "Kenya",
"logoUrl": null,
"kybStatus": "pending",
"createdAt": "2025-11-04T09:22:11.000Z"
}
}
id — you will need it for every org-scoped request. You are automatically assigned the owner role the moment the organization is created. No separate membership step is needed.
Slug rules
The slug field becomes a permanent, unique identifier for your organization across the platform. It must be:
- Lowercase letters, numbers, and hyphens only
- Globally unique across all Nyota Imara organizations
The API automatically replaces any disallowed characters with hyphens. If the slug you requested is already taken, the server returns 409 Conflict.
Make organization-scoped requests
After creating an organization, pass its id in the X-Organization-Id header on every request that operates within that org’s context — billing, commerce, logistics, team management, and more.
curl https://api.nyotaimara.com/v1/organizations/org_01j9kxp8a3bvc0nqrtzwmde4fy \
-H "Authorization: Bearer <your_token>" \
-H "X-Organization-Id: org_01j9kxp8a3bvc0nqrtzwmde4fy"
The X-Organization-Id header tells the server which organization context to enforce for authorization checks. Requests that require an org context will return 403 Forbidden if this header is missing or mismatched.
Update your organization
Use PATCH /v1/organizations/:id to update any combination of the following fields: name, logoUrl, kraPin, billingEmail, address, city, country.
curl -X PATCH https://api.nyotaimara.com/v1/organizations/org_01j9kxp8a3bvc0nqrtzwmde4fy \
-H "Authorization: Bearer <your_token>" \
-H "X-Organization-Id: org_01j9kxp8a3bvc0nqrtzwmde4fy" \
-H "Content-Type: application/json" \
-d '{
"billingEmail": "billing@savanasupplies.co.ke",
"logoUrl": "https://cdn.savanasupplies.co.ke/logo.png"
}'
{
"success": true,
"message": "Organization settings updated successfully."
}
Updating an organization requires the org:organization:update policy. Only owners and admins have this permission by default.
Request body reference
| Field | Type | Required | Description |
|---|
name | string | Yes | Display name of your organization |
slug | string | Yes | Unique, URL-safe identifier (lowercase, hyphens only) |
kraPin | string | No | Kenya Revenue Authority PIN — required for KYB |
billingEmail | string | No | Email address for billing notifications and invoices |
address | string | No | Street address |
city | string | No | City |
country | string | No | Defaults to "Kenya" |
