Space Authorization

The space-authorization domain in the Aimable Platform API (v0.1.0) enables fine-grained permission checks within a collaborative workspace ("space"). It allows applications to verify whether a user or service (referred to as a principal) has a specific permission in a given space. This is essential for enforcing access control in multi-user environments—ensuring users can only perform actions they are authorized for, such as editing content, managing members, or deleting resources.

Authorization decisions are based on roles, policies, and explicit grants within a space. The API does not manage those policies directly but provides a lightweight way to check if a principal is allowed to perform an action, making it ideal for frontend guards or backend enforcement.

Key Concepts

Space: A logical container for resources and collaboration. Identified by a UUID (space_id).
Principal: An entity (user or service) whose permissions are being checked. Identified by principal_id.
Permission Key: A string representing a specific action (e.g., document:write, members:invite).
Check: A query to determine if a principal has a given permission in a space.

Authentication is required using either a Bearer token (Authorization: Bearer <token>) or an API key (X-API-Key). If neither is provided, or if the principal lacks the required permission, the API returns an appropriate error.

Check Space Permission

Use this endpoint to validate whether a principal has a specific permission in a space.

Request

GET /api-proxy/v1/spaces/550e8400-e29b-41d4-a716-446655440000/authorization/check?permission_key=document:write&principal_id=user_123
Authorization: Bearer <access_token>

Replace 550e8400-e29b-41d4-a716-446655440000 with the actual space_id.
Replace document:write with the desired permission key.
principal_id is optional. If omitted, the identity from the token or API key is used.

Example curl Request

curl -X GET \
  'https://platform.aimable.com/api-proxy/v1/spaces/550e8400-e29b-41d4-a716-446655440000/authorization/check?permission_key=document:delete&principal_id=user_789' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxxxx' \
  -H 'Content-Type: application/json'

Successful Response (200 OK)

{}

The response body is empty on success. A 200 status indicates the principal has the requested permission.

Error Responses

| Status | Meaning | |-------|--------| | 401 Unauthorized | No valid authentication was provided. | | 403 Forbidden | The principal exists but does not have the requested permission. | | 422 Unprocessable Entity | Invalid parameters (e.g., malformed UUID, missing permission_key). |

Example 422 Response

{
  "detail": [
    {
      "loc": ["query", "permission_key"],
      "msg": "Field required",
      "type": "missing",
      "input": null
    }
  ]
}

Common Workflows

1. Secure UI Elements Based on Permissions

Before showing a "Delete Document" button, check if the current user has the document:delete permission.

Sequence:

Retrieve the current space_id and user_id.
Call the check endpoint.

GET /api-proxy/v1/spaces/550e8400-e29b-41d4-a716-446655440000/authorization/check?permission_key=document:delete&principal_id=user_789
Authorization: Bearer <token>

If response is 200, show the button.
If 403, hide or disable it.

2. Backend Action Enforcement

Before processing a request to invite a new member, verify the caller has members:invite rights.

GET /api-proxy/v1/spaces/550e8400-e29b-41d4-a716-446655440000/authorization/check?permission_key=members:invite
Authorization: Bearer <token>

Omit principal_id to check permissions for the authenticated principal.

If the response is not 200, reject the request early with 403 Forbidden.

Authentication & Error Handling

Authentication: Provide either:
- Authorization: Bearer <token>
- X-API-Key: <api_key>
Idempotent Checks: The check endpoint is idempotent and safe—it does not alter state.
Caching: Consider caching results briefly (e.g., 5–10 minutes) to reduce latency, especially for UI rendering.
Fail Securely: Always treat errors (401, 403, 5xx) as denied permissions in production.

This domain is critical for building secure, role-aware applications on the Aimable Platform. By integrating permission checks early, you ensure users only access what they’re entitled to—without overcomplicating your logic.

GET /v1/spaces/{space_id}/authorization/check — Check Space Permission

Space Authorization