Skip to main content
An organization is the top-level workspace for your business on Nyota Imara. Every platform feature that goes beyond your personal account — billing, commerce, logistics, team management — operates inside an organization. You can belong to multiple organizations simultaneously, each with its own members, roles, and KYB verification status.

​
Creating an organization

When you create an organization, Nyota Imara automatically assigns you the owner role. You supply a name and a slug at creation time; the slug is your organization’s unique identifier across the platform and cannot be changed after it is set. 
POST /v1/organizations

{
  "name": "Savanna Logistics Ltd",
  "slug": "savanna-logistics",
  "kraPin": "A123456789X",
  "billingEmail": "billing@savannalogistics.co.ke",
  "city": "Nairobi",
  "country": "Kenya"
}
Slugs are lowercased and sanitized automatically — any character that is not a letter, digit, or hyphen is replaced with a hyphen. If the slug you choose is already taken, the API returns 409 Conflict.

​
Personal context vs. organization context

Nyota Imara uses two request contexts:
  • Personal context — requests made without an X-Organization-Id header. Use this to list your organizations (GET /v1/organizations) or accept an invitation.
  • Organization context — requests that include the X-Organization-Id header. The value must be the UUID of an organization you belong to. This header activates your organization-scoped role and its permission set for that request.
# Personal context — no header needed
GET /v1/organizations

# Organization context — header required
GET /v1/organizations/org_01HXYZ/members
X-Organization-Id: org_01HXYZ
Organization-scoped endpoints reject requests that omit X-Organization-Id, or where the header value does not match the organization ID in the URL path.

​
Built-in roles

Every organization ships with four protected roles. These roles cannot be renamed or deleted.
RoleWhat it can do
ownerFull access to all organization settings, members, billing, KYB, IAM, and every platform service. Created automatically for the organization’s founder.
adminManage organization settings, invite and remove members, view and submit KYB, and read billing information. Cannot delete the organization or modify owner accounts.
billingCreate and manage payment methods, initiate payments, and view invoices. No access to member management or org settings.
memberBasic read access to organization data and shared resources. Cannot change settings, invite others, or access billing.
Organization owners can create custom roles with any combination of granular permissions. See Permissions for details.

​
Members and invitations

To invite someone to your organization, send a POST request with the invitee’s email address and the role you want to assign. Nyota Imara generates a time-limited invite link and emails it automatically. 
POST /v1/organizations/:id/invites

{
  "email": "amina@savannalogistics.co.ke",
  "roleName": "billing"
}
Invitation links expire after 7 days. The invitee must have a Nyota Imara account and be signed in to accept. They accept by calling POST /v1/organizations/invites/accept with the token from the link.
Sending a second invite to someone who is already a member returns 409 Conflict. Check GET /v1/organizations/:id/members first — it returns both active members and all pending invitations in a single response.

​
KYB verification requirement

Some platform features — including payment processing and order management — require your organization to be KYB-verified. Until verification is complete, your organization’s kybStatus remains pending or none. Submit your business documents at POST /v1/organizations/:id/kyb. Once your submission is reviewed and approved, kybStatus changes to verified and gated features become available. See Identity Verification for the full document requirements.

​
Org-scoped API endpoints

All endpoints that act on an organization follow the pattern /v1/organizations/:id/... and require the X-Organization-Id header. The table below lists the primary endpoints.
MethodPathPermission required
GET/v1/organizationsPersonal context
POST/v1/organizationsplatform:org:create
GET/v1/organizations/:idorg:organization:read
PATCH/v1/organizations/:idorg:organization:update
GET/v1/organizations/:id/membersorg:member:read
POST/v1/organizations/:id/invitesorg:member:invite
GET/v1/organizations/:id/kyborg:kyb:read
POST/v1/organizations/:id/kyborg:kyb:submit
GET/v1/organizations/iam/rolesorg:organization:read