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.

Steps

1. Store the key and the API base URL:

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

2. Create the organization with its first admin:

   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:

   {
     "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:

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

   {
     "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:

   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:

   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"}'

   {"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:

   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}'

   {"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:

   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:

   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.

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

Next steps

• Organization members, invites and deletion: Organizations API.
• How the role combines with workspace changes: Roles and permissions.