AimableDocs
DocsAPI Reference

Principal

Introduction to Principal Domain

The "principal" domain in the FastAPI API is designed to manage and interact with the user's identity and their associated roles within different tenants. This domain is crucial for applications that require multi-tenancy support, allowing users to switch contexts between different organizational units or projects. Understanding and utilizing the principal domain effectively enables developers to build applications that are both secure and flexible, providing users with tailored access to resources based on their memberships and roles.

Key Concepts

Principal

A principal represents the authenticated user interacting with the API. It is the identity under which all actions are performed, and it determines what resources the user can access.

Tenant

A tenant is an organizational unit or a project within the application. Users can be members of multiple tenants, and switching between them allows users to access different sets of resources.

Membership

Membership refers to the association between a user and a tenant. It defines the user's role and permissions within that tenant.

Common Workflows

Switching Tenants

Switching tenants is a common operation for users who are members of multiple organizational units. This operation allows users to change the context of their interactions with the API.

  1. Switch Tenant: Use the POST /v1/auth/switch-tenant endpoint to change the active tenant for the user.

Retrieving User Information

Users often need to retrieve their own information or their memberships to understand their current context and permissions.

  1. Get Current User: Use the GET /v1/me endpoint to fetch details about the authenticated user.
  2. List Memberships: Use the GET /v1/me/memberships endpoint to list all tenant memberships for the user.

Practical Examples

Switching Tenants

To switch the active tenant for a user, send a POST request to the /v1/auth/switch-tenant endpoint. This operation may require an API key for authentication.

curl -X POST "https://api.example.com/v1/auth/switch-tenant" \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{"tenant_id": "12345"}'

Retrieving Current User Information

To get information about the currently authenticated user, use the following GET request:

curl -X GET "https://api.example.com/v1/me" \
-H "X-API-Key: your-api-key"

Listing User Memberships

To list all the memberships for the current user, execute the following GET request:

curl -X GET "https://api.example.com/v1/me/memberships" \
-H "X-API-Key: your-api-key"

Important Considerations

Authentication

While the X-API-Key header is optional, it is recommended to include it in requests to ensure secure access to the API. Without proper authentication, requests may fail or return limited information.

Error Handling

Ensure to handle potential errors gracefully. Common errors include unauthorized access (401) and resource not found (404). Implement appropriate error handling in your application to provide a smooth user experience.

Pagination

For endpoints that return lists, consider implementing pagination to handle large datasets efficiently. Although not detailed here, check the API documentation for pagination support and best practices.

By understanding and utilizing the principal domain effectively, developers can create robust applications that manage user identities and permissions across multiple tenants, enhancing both security and user experience.