AimableDocs
DocsAPI Reference

Space Roles

Introduction to Space-Roles

The "space-roles" domain in the FastAPI API is designed to manage roles within a specific space. Roles define the permissions and access levels for members within a space, enabling effective collaboration and control over resources. This domain is crucial for maintaining organized and secure access to space resources, ensuring that each member has the appropriate permissions to perform their tasks.

Key Concepts and Entities

  • Space: A container or environment where resources are managed and accessed by members.
  • Member: An individual user who is part of a space.
  • Role: A set of permissions that can be assigned to a member within a space. Roles determine what actions a member can perform.
  • Principal ID: A unique identifier for a member within a space.
  • Role ID: A unique identifier for a role within a space.

Common Workflows

Listing Member Roles

To view the roles assigned to a specific member within a space, use the GET /v1/spaces/{space_id}/members/{principal_id}/roles endpoint. This is useful for auditing and understanding the permissions a member has.

curl -X GET "https://api.example.com/v1/spaces/{space_id}/members/{principal_id}/roles" \
-H "X-API-Key: your_api_key"

Assigning a Role to a Member

To assign a new role to a member, use the POST /v1/spaces/{space_id}/members/{principal_id}/roles endpoint. This action is essential when onboarding new members or changing a member's responsibilities.

curl -X POST "https://api.example.com/v1/spaces/{space_id}/members/{principal_id}/roles" \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
  "role_id": "role_id_to_assign"
}'

Removing a Role from a Member

To remove a role from a member, use the DELETE /v1/spaces/{space_id}/members/{principal_id}/roles/{role_id} endpoint. This is often used when a member's responsibilities change or they leave the space.

curl -X DELETE "https://api.example.com/v1/spaces/{space_id}/members/{principal_id}/roles/{role_id}" \
-H "X-API-Key: your_api_key"

Listing All Roles in a Space

To get a list of all available roles within a space, use the GET /v1/spaces/{space_id}/roles endpoint. This helps in understanding the roles that can be assigned to members.

curl -X GET "https://api.example.com/v1/spaces/{space_id}/roles" \
-H "X-API-Key: your_api_key"

Important Considerations

  • Authentication: Most endpoints require an X-API-Key header for authentication. Ensure your API key is kept secure and is not exposed in public repositories.
  • Error Handling: Handle HTTP status codes appropriately. For example, a 404 response indicates that the specified resource was not found, while a 401 response indicates authentication issues.
  • Pagination: When listing roles, consider implementing pagination if the number of roles is large, although this is not explicitly detailed in the current version.
  • Idempotency: When assigning roles, ensure that the operation is idempotent, meaning multiple identical requests should have the same effect as a single request.

By understanding and utilizing these endpoints effectively, developers can manage space roles efficiently, ensuring that members have the correct permissions to perform their tasks within a space.