AimableDocs
DocsAPI ReferenceRelease Notes

Space Members

Updated 9 July 2026

Space Members API

The Space Members API enables you to manage user access to a space—a shared environment within the Aimable Platform. This domain allows you to invite users, manage memberships, accept invitations, and control access rights programmatically. It's essential for building collaboration features, automating team onboarding, or integrating with external identity systems.

Key Concepts

  • Space: A logical container for collaboration. Identified by a space_id (UUID).
  • Member: A user who has joined the space. Represented by a principal_id (UUID).
  • Invite: A time-limited token granting access to join a space. Can be created, updated, accepted, or revoked.
  • Principal: A user or service identity in the system, identified globally by principal_id.

Authentication is required for all endpoints using a Bearer token in the Authorization header. Optional X-API-Key header may be used for additional identification.

How to Use the API

1. Invite a User to a Space

Creates an invite for a specific user (principal_id) to join a space.

bash
curl -X POST 'https://api.aimable.com/api/v1/spaces/123e4567-e89b-12d3-a456-426614174000/invites' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "principal_id": "987e6543-e21b-11d3-a456-426614174001",
    "expires_at": "2025-12-31T23:59:59Z"
  }'

Response (201 Created):

json
{
  "invite_id": "abcde123-4567-89ab-cdef-1234567890ab",
  "space_id": "123e4567-e89b-12d3-a456-426614174000",
  "principal_id": "987e6543-e21b-11d3-a456-426614174001",
  "status": "pending",
  "expires_at": "2025-12-31T23:59:59Z",
  "created_at": "2024-06-01T10:00:00Z"
}

2. Accept an Invite

A user accepts an invitation to join a space.

bash
curl -X POST 'https://api.aimable.com/api/v1/spaces/123e4567-e89b-12d3-a456-426614174000/invites/abcde123-4567-89ab-cdef-1234567890ab/accept' \
  -H 'Authorization: Bearer <user_access_token>'

Response (200 OK):

json
{
  "message": "Successfully joined the space"
}

Note: The principal_id of the authenticated user must match the one in the invite.

3. List All Members in a Space

Retrieve current members of a space.

bash
curl -X GET 'https://api.aimable.com/api/v1/spaces/123e4567-e89b-12d3-a456-426614174000/members' \
  -H 'Authorization: Bearer <access_token>'

Response (200 OK):

json
[
  {
    "principal_id": "987e6543-e21b-11d3-a456-426614174001",
    "status": "active",
    "joined_at": "2024-06-01T10:05:00Z"
  },
  {
    "principal_id": "f00e0000-e00b-00d0-a000-000000000000",
    "status": "active",
    "joined_at": "2024-05-15T09:20:00Z"
  }
]

4. Remove a Member

Remove a user from the space.

bash
curl -X DELETE 'https://api.aimable.com/api/v1/spaces/123e4567-e89b-12d3-a456-426614174000/members/987e6543-e21b-11d3-a456-426614174001' \
  -H 'Authorization: Bearer <access_token>'

Response (200 OK):

json
{
  "message": "Member removed successfully"
}

Common Workflows

Invite and Add a New Team Member

  1. Create an invite for the new user:

    bash
    POST /api/v1/spaces/{space_id}/invites

  2. User accepts the invite:

    bash
    POST /api/v1/spaces/{space_id}/invites/{invite_id}/accept

  3. Verify membership:

    bash
    GET /api/v1/spaces/{space_id}/members

Alternatively, if you have admin rights and want to add directly without an invite:

bash
POST /api/v1/spaces/{space_id}/members
{ "principal_id": "..." }

See Authentication & errors for request authentication and the standard error responses.

Use this API to build dynamic access control, team management dashboards, or automated provisioning flows. Always validate responses and handle revocation or expiration of invites appropriately.

Related Endpoints

See also