AimableDocs
DocsAPI ReferenceRelease Notes

Principal

Updated 9 July 2026

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/v1/me)

Retrieves information about the currently authenticated principal.

Example Request:

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

Response (200 OK):

json
{
  "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/v1/me/memberships)

Lists all tenants the principal has access to.

Example Request:

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

Response (200 OK):

json
[
  {
    "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/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:

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

Response (200 OK):

json
{
  "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:
    bash
    GET /api/v1/me
  3. List memberships to show available tenants:
    bash
    GET /api/v1/me/memberships
  4. Switch to desired tenant:
    bash
    POST /api/v1/auth/switch-tenant
{ "tenant_id": "tnt-789ghi" }
  5. Use the new access_token for all future requests to that tenant’s resources.

See Authentication & errors for request authentication and the standard error responses.

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

See also