> ## Documentation Index
> Fetch the complete documentation index at: https://handbook.nyotaimara.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Organizations: How B2B Workspaces Work on Nyota Imara

> Learn how Nyota Imara organizations work — roles, membership, KYB verification, and switching context with the X-Organization-Id header.

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.

```json theme={null}
POST /v1/organizations

{
  "name": "Savanna Logistics Ltd",
  "slug": "savanna-logistics",
  "kraPin": "A123456789X",
  "billingEmail": "billing@savannalogistics.co.ke",
  "city": "Nairobi",
  "country": "Kenya"
}
```

<Note>
  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`.
</Note>

## 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.

```bash theme={null}
# Personal context — no header needed
GET /v1/organizations

# Organization context — header required
GET /v1/organizations/org_01HXYZ/members
X-Organization-Id: org_01HXYZ
```

<Warning>
  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.
</Warning>

## Built-in roles

Every organization ships with four protected roles. These roles cannot be renamed or deleted.

| Role        | What it can do                                                                                                                                                       |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **owner**   | Full access to all organization settings, members, billing, KYB, IAM, and every platform service. Created automatically for the organization's founder.              |
| **admin**   | Manage organization settings, invite and remove members, view and submit KYB, and read billing information. Cannot delete the organization or modify owner accounts. |
| **billing** | Create and manage payment methods, initiate payments, and view invoices. No access to member management or org settings.                                             |
| **member**  | Basic read access to organization data and shared resources. Cannot change settings, invite others, or access billing.                                               |

<Info>
  Organization owners can create custom roles with any combination of granular permissions. See [Permissions](/concepts/permissions) for details.
</Info>

## 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.

```json theme={null}
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.

<Tip>
  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.
</Tip>

## 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](/concepts/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.

| Method  | Path                            | Permission required       |
| ------- | ------------------------------- | ------------------------- |
| `GET`   | `/v1/organizations`             | Personal context          |
| `POST`  | `/v1/organizations`             | `platform:org:create`     |
| `GET`   | `/v1/organizations/:id`         | `org:organization:read`   |
| `PATCH` | `/v1/organizations/:id`         | `org:organization:update` |
| `GET`   | `/v1/organizations/:id/members` | `org:member:read`         |
| `POST`  | `/v1/organizations/:id/invites` | `org:member:invite`       |
| `GET`   | `/v1/organizations/:id/kyb`     | `org:kyb:read`            |
| `POST`  | `/v1/organizations/:id/kyb`     | `org:kyb:submit`          |
| `GET`   | `/v1/organizations/iam/roles`   | `org:organization:read`   |