AimableDocs
DocsAPI Reference

Space Roles

Space Roles Management

The space-roles domain in the Aimable Platform API (v0.1.0) enables fine-grained access control within a space by managing role assignments for members. A space represents a logical container (such as a workspace or project), and roles define what actions a member can perform within that space.

This API allows you to:

  • List all roles assigned to a specific member
  • Assign new roles to a member
  • Remove existing roles from a member
  • List all available roles in a space

Managing space roles is essential for enforcing security, enabling collaboration, and ensuring users have the right level of access.

Key Concepts

  • Space: A container with its own set of resources and permissions. Identified by a space_id.
  • Principal: A user or service account (referred to by principal_id) who can be assigned roles.
  • Role: A named set of permissions (e.g., admin, editor, viewer). Can be referenced by role_id or role_key.
  • Assignment: A link between a principal and a role within a space.

Authentication is required for all operations using a Bearer token in the Authorization header. Some actions may also require an X-API-Key header depending on configuration.

Common Workflows

1. Assign a Role to a Member

Use this to grant a user (principal_id) a specific role in a space.

Endpoint: POST /api-proxy/v1/spaces/{space_id}/members/{principal_id}/roles

Example:

curl -X POST 'https://platform.aimable.com/api-proxy/v1/spaces/123e4567-e89b-12d3-a456-426614174000/members/987e6543-e21b-11e9-b8a3-2a46e45f8e01/roles' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "role_key": "space.editor"
  }'

Success Response (201 Created):

{
  "role_id": "roles/123",
  "role_key": "space.editor",
  "space_id": "123e4567-e89b-12d3-a456-426614174000",
  "principal_id": "987e6543-e21b-11e9-b8a3-2a46e45f8e01",
  "assigned_at": "2025-04-05T10:00:00Z"
}

💡 You can use either role_id or role_key in the request body — but at least one must be provided.

2. List All Roles Assigned to a Member

Check what permissions a user currently has in a space.

Endpoint: GET /api-proxy/v1/spaces/{space_id}/members/{principal_id}/roles

Example:

curl -X GET 'https://platform.aimable.com/api-proxy/v1/spaces/123e4567-e89b-12d3-a456-426614174000/members/987e6543-e21b-11e9-b8a3-2a46e45f8e01/roles' \
  -H 'Authorization: Bearer <your-access-token>'

Response (200 OK):

[
  {
    "role_id": "roles/101",
    "role_key": "space.admin",
    "assigned_at": "2025-01-15T08:30:00Z"
  },
  {
    "role_id": "roles/102",
    "role_key": "space.editor",
    "assigned_at": "2025-02-20T14:20:00Z"
  }
]

3. Remove a Role from a Member

Revoke a specific role from a user.

Endpoint: DELETE /api-proxy/v1/spaces/{space_id}/members/{principal_id}/roles/{role_id}

Example:

curl -X DELETE 'https://platform.aimable.com/api-proxy/v1/spaces/123e4567-e89b-12d3-a456-426614174000/members/987e6543-e21b-11e9-b8a3-2a46e45f8e01/roles/roles/102' \
  -H 'Authorization: Bearer <your-access-token>'

Response (200 OK):

{
  "success": true,
  "message": "Role unassigned successfully"
}

4. List All Available Roles in a Space

Discover which roles can be assigned in a given space.

Endpoint: GET /api-proxy/v1/spaces/{space_id}/roles

Example:

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

Response (200 OK):

[
  {
    "role_id": "roles/101",
    "role_key": "space.admin",
    "display_name": "Space Admin",
    "description": "Full control over the space"
  },
  {
    "role_id": "roles/102",
    "role_key": "space.editor",
    "display_name": "Editor",
    "description": "Can edit content but not manage members"
  },
  {
    "role_id": "roles/103",
    "role_key": "space.viewer",
    "display_name": "Viewer",
    "description": "Read-only access"
  }
]

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 | You don’t have permission to modify roles in this space | | 422 | Invalid input (e.g., malformed UUID, missing role_key) — includes detailed loc, msg, and type fields |

Example 422 response:

{
  "detail": [
    {
      "loc": ["body", "role_key"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Typical Workflow

  1. List available roles in the space to know what can be assigned.
  2. Assign a role to a member using role_key.
  3. List member roles to confirm the assignment.
  4. Later, remove the role if access should be revoked.

This domain gives you full control over dynamic access management in multi-user environments.

Related Endpoints