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

# Create and Configure Your Nyota Imara Organization

> Set up a Nyota Imara organization, configure your business details, and learn how to use the X-Organization-Id header for scoped API requests.

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.

<Steps>
  <Step title="Send the create request">
    ```bash theme={null}
    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"
      }'
    ```
  </Step>

  <Step title="Receive the organization record">
    A `201 Created` response returns the new organization object:

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

    Save the `id` — you will need it for every org-scoped request.
  </Step>
</Steps>

<Note>
  You are automatically assigned the **owner** role the moment the organization is created. No separate membership step is needed.
</Note>

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

```bash theme={null}
curl https://api.nyotaimara.com/v1/organizations/org_01j9kxp8a3bvc0nqrtzwmde4fy \
  -H "Authorization: Bearer <your_token>" \
  -H "X-Organization-Id: org_01j9kxp8a3bvc0nqrtzwmde4fy"
```

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

***

## Update your organization

Use `PATCH /v1/organizations/:id` to update any combination of the following fields: `name`, `logoUrl`, `kraPin`, `billingEmail`, `address`, `city`, `country`.

```bash theme={null}
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"
  }'
```

A successful response returns:

```json theme={null}
{
  "success": true,
  "message": "Organization settings updated successfully."
}
```

<Warning>
  Updating an organization requires the `org:organization:update` policy. Only owners and admins have this permission by default.
</Warning>

***

## 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"`                                 |