AimableDocs
DocsAPI Reference

Principal

Principal Management

The principal domain in the Aimable Platform API (v0.1.0) represents the authenticated user or service account making requests to the system. It encompasses identity, tenant membership, and session scoping. Understanding the principal is essential for managing multi-tenant access, switching contexts, and retrieving user-specific information.

A principal is typically authenticated via an access token (e.g., OAuth2 or API key), and their permissions are scoped by tenant. The principal endpoints allow you to retrieve user details, list available tenants (memberships), and switch between tenants by obtaining a new scoped session token.

Key Concepts

  • Principal: The authenticated entity (user or service) making API calls.
  • Tenant: A logical isolation boundary for data and permissions. A principal may belong to multiple tenants.
  • Session Token: A short-lived token scoped to a specific tenant, obtained after authentication and tenant switching.
  • Membership: A principal's association with a tenant, determining what resources they can access.

Authentication is required for all endpoints using a valid Authorization: Bearer <token> header. Optional X-API-Key headers may be used for additional identification or rate limiting.

Core Endpoints

Get Current Principal (GET /api-proxy/v1/me)

Retrieves information about the currently authenticated principal.

Example Request:

curl -X GET 'https://platform.aimable.com/api-proxy/v1/me' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Response (200 OK):

{
  "id": "usr-123abc",
  "email": "user@example.com",
  "name": "Jane Doe",
  "created_at": "2023-04-01T12:00:00Z"
}

Use this to verify authentication and retrieve user metadata.

List Tenant Memberships (GET /api-proxy/v1/me/memberships)

Lists all tenants the principal has access to.

Example Request:

curl -X GET 'https://platform.aimable.com/api-proxy/v1/me/memberships' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Response (200 OK):

[
  {
    "tenant_id": "tnt-456def",
    "name": "Acme Corp",
    "role": "admin",
    "joined_at": "2023-04-01T12:00:00Z"
  },
  {
    "tenant_id": "tnt-789ghi",
    "name": "Beta Inc",
    "role": "member",
    "joined_at": "2023-05-15T08:30:00Z"
  }
]

This helps users understand which organizations they can operate within.

Switch Tenant (POST /api-proxy/v1/auth/switch-tenant)

Switches the principal's context to a different tenant and returns a new session token scoped to that tenant.

Example Request:

curl -X POST 'https://platform.aimable.com/api-proxy/v1/auth/switch-tenant' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  -H 'Content-Type: application/json' \
  -d '{
    "tenant_id": "tnt-789ghi"
  }'

Response (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.tenant-scoped-token",
  "token_type": "bearer",
  "expires_in": 3600
}

Use the returned access_token for subsequent calls to resources in the new tenant.

Common Workflow: Switching Tenants

Developers typically follow this flow when building multi-tenant applications:

  1. Authenticate and obtain an initial access token (outside this domain).
  2. Get user info to confirm identity: 
    GET /api-proxy/v1/me
  3. List memberships to show available tenants: 
    GET /api-proxy/v1/me/memberships
  4. Switch to desired tenant: 
    POST /api-proxy/v1/auth/switch-tenant
{ "tenant_id": "tnt-789ghi" }
  5. Use the new access_token for all future requests to that tenant’s resources.

Authentication & Error Handling

All endpoints require a valid bearer token:

Authorization: Bearer <token>

Optional:

X-API-Key: your-api-key

Common Errors

  • 401 Unauthorized: Missing or invalid access token.
  • 403 Forbidden: Insufficient permissions for the action.
  • 422 Unprocessable Entity: Invalid request body. Example: 
    {
  "detail": [
    {
      "loc": ["body", "tenant_id"],
      "msg": "Field required",
      "type": "value_error.missing"
    }
  ]
}

Always validate request payloads and handle token expiration gracefully by re-authenticating or refreshing tokens.

By leveraging the principal domain, developers can build robust, tenant-aware applications that securely manage user identity and context switching within the Aimable Platform.

Related Endpoints