> Documentation index: [/llms.txt](/llms.txt). Every page as one file: [/llms-full.txt](/llms-full.txt).

# Set up a client

Set up a client [#set-up-a-client]

Set up a new client's organization, workspace, role and members with a platform key, without the web app.

Requires: a platform admin's [platform key](../api-basics/authentication).

Steps [#steps]

1. Store the key and the [API base URL](../get-started#base-urls):

   ```bash
   export CENTRAL_HUB_URL="https://platform.alomana.com"
   export ALO_PLATFORM_API_KEY="sk-…"
   ```

2. Create the organization with its first admin:

   ```bash
   curl -X POST "$CENTRAL_HUB_URL/api/v1/platform-admin/organizations/" \
     -H "X-API-Key: $ALO_PLATFORM_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"name": "Acme Corp", "admin_email": "lead@acme.com"}'
   ```

   The first admin gets an invite that expires in 7 days, also when they already have an account; they join when they accept it. Note `organization.id`:

   ```json
   {
     "id": null,
     "organization": {
       "address_line1": null,
       "address_line2": null,
       "city": null,
       "state_or_province": null,
       "postal_code": null,
       "country": null,
       "id": "52e6de15-f609-44c5-80a1-3928869a9652",
       "name": "Acme Corp",
       "member_count": 0,
       "created_at": "2026-10-13T16:00:54.924957Z",
       "deletion_requested_at": null,
       "deleted_at": null
     },
     "admin": {
       "id": null,
       "invite": {
         "id": 1,
         "invited_email": "lead@acme.com",
         "role": "admin",
         "status": "pending",
         "token_preview": "sk-Qy.....ga2I",
         "expires_at": "2026-10-20T16:00:54.931501Z",
         "created_at": "2026-10-13T16:00:54.932214Z",
         "seat_tier_slug": null,
         "seat_name": null
       }
     }
   }
   ```

3. Create a workspace inside the organization:

   ```bash
   curl -X POST "$CENTRAL_HUB_URL/api/v1/platform-admin/spaces/" \
     -H "X-API-Key: $ALO_PLATFORM_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"name": "Acme Operations", "organization_id": "52e6de15-f609-44c5-80a1-3928869a9652"}'
   ```

   The response is the workspace; note `slug`. The key's owner becomes the workspace's Admin; the create response does not count members (`member_count: 0`).

   ```json
   {
     "id": 281,
     "slug": "acme-operations",
     "name": "Acme Operations",
     "status": "active",
     "is_default": false,
     "created_by_id": 1,
     "updated_by_id": 1,
     "created_at": "2026-10-13T16:00:56.482274Z",
     "updated_at": "2026-10-13T16:00:56.482277Z",
     "role_slug": "admin",
     "role_name": null,
     "organization_id": "52e6de15-f609-44c5-80a1-3928869a9652",
     "is_creator": true,
     "created_by_email": null,
     "member_count": 0,
     "is_shared": false
   }
   ```

4. Find the permission to give the new role. Each entry has an `id`, `resource_type` and `action`:

   ```bash
   curl "$CENTRAL_HUB_URL/api/v1/platform-admin/organizations/52e6de15-f609-44c5-80a1-3928869a9652/roles/permissions/" \
     -H "X-API-Key: $ALO_PLATFORM_API_KEY"
   ```

5. Create a custom role. It starts empty and appears in every workspace of the organization:

   ```bash
   curl -X POST "$CENTRAL_HUB_URL/api/v1/platform-admin/organizations/52e6de15-f609-44c5-80a1-3928869a9652/roles/" \
     -H "X-API-Key: $ALO_PLATFORM_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"name": "Analyst"}'
   ```

   ```json
   {"id": 929, "slug": "analyst", "name": "Analyst", "permission_ids": [], "inherited_permission_ids": []}
   ```

6. Give the role a permission, here Read connections (`connection:read`). Take its `id` from the list in step 4; IDs differ per deployment:

   ```bash
   curl -X PUT "$CENTRAL_HUB_URL/api/v1/platform-admin/organizations/52e6de15-f609-44c5-80a1-3928869a9652/roles/929/permissions/60/" \
     -H "X-API-Key: $ALO_PLATFORM_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"enabled": true}'
   ```

   ```json
   {"id": 929, "slug": "analyst", "name": "Analyst", "permission_ids": [60], "inherited_permission_ids": []}
   ```

7. Add the organization's admin to the workspace. Organization membership does not give access to its workspaces:

   ```bash
   curl -X POST "$CENTRAL_HUB_URL/api/v1/spaces/current/invites/" \
     -H "X-API-Key: $ALO_PLATFORM_API_KEY" \
     -H "X-Space-Slug: acme-operations" \
     -H "Content-Type: application/json" \
     -d '{"email": "lead@acme.com", "role_slug": "admin"}'
   ```

8. Invite the first member with the custom role:

   ```bash
   curl -X POST "$CENTRAL_HUB_URL/api/v1/spaces/current/invites/" \
     -H "X-API-Key: $ALO_PLATFORM_API_KEY" \
     -H "X-Space-Slug: acme-operations" \
     -H "Content-Type: application/json" \
     -d '{"email": "ana@acme.com", "role_slug": "analyst"}'
   ```

   The response has `added_directly: false` and a `pending` invite, as in [Members and invites](./members-and-invites).

9. Verify: `GET /api/v1/spaces/current/roles/` with `X-Space-Slug: acme-operations` lists `analyst` with `permission_ids: [60]`.

Next steps [#next-steps]

* Organization members, invites and deletion: [Organizations API](../platform/organizations).
* How the role combines with workspace changes: [Roles and permissions](./roles-and-permissions).