AimableDocs
DocsAPI Reference

Space Members

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.

curl -X POST 'https://api.aimable.com/api-proxy/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):

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

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

Response (200 OK):

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

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

Response (200 OK):

[
  {
    "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.

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

Response (200 OK):

{
  "message": "Member removed successfully"
}

Common Workflows

Invite and Add a New Team Member

  1. Create an invite for the new user:

    POST /api-proxy/v1/spaces/{space_id}/invites

  2. User accepts the invite:

    POST /api-proxy/v1/spaces/{space_id}/invites/{invite_id}/accept

  3. Verify membership:

    GET /api-proxy/v1/spaces/{space_id}/members

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

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

Authentication & Error Handling

All endpoints require authentication via:

Authorization: Bearer <access_token>

Optional:

X-API-Key: <api_key>

Common Errors

| Status | Meaning | |-------|--------| | 401 | Missing or invalid access token | | 403 | Authenticated but not authorized (e.g., not a space admin) | | 422 | Invalid input (e.g., malformed UUID, missing field) |

Example 422 response:

{
  "detail": [
    {
      "loc": ["body", "principal_id"],
      "msg": "Input should be a valid UUID",
      "type": "uuid_type",
      "input": "not-a-uuid"
    }
  ]
}

Ensure proper validation of space_id, invite_id, and principal_id as UUIDs before making requests.

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