AimableDocs
DocsAPI ReferenceRelease Notes

Admin Tenant

Updated 9 July 2026

Admin Tenant Management

The admin-tenant domain of the Aimable Platform API (v0.1.0) provides administrative capabilities for managing tenants, roles, permissions, and principals (users or services). This domain is essential for platform operators and system administrators who need to configure access control, onboard new tenants, and manage platform-wide security policies.

Key entities include:

  • Tenant: A top-level organizational unit in the platform.
  • Principal: An actor (user or service) that can be assigned roles and permissions.
  • Role: A collection of permissions assigned to principals.
  • Permission: The most granular access control unit defining what actions are allowed.

All endpoints require authentication via a valid access token in the Authorization header. Optional X-API-Key headers may also be used depending on configuration.

Key Endpoints and Usage

Create a New Tenant

Use this to onboard a new organization into the platform.

bash
curl -X POST 'https://api.aimable.com/api/v1/admin/tenants' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Acme Corp",
    "external_reference": "acme-corp-12345"
  }'

Response (201 Created):

json
{
  "id": "tenant_123e4567-e89b-12d3-a456-426614174000",
  "name": "Acme Corp",
  "external_reference": "acme-corp-12345",
  "status": "active"
}

Create a Role and Assign Permissions

Roles bundle permissions for easier management.

bash
# Create a role
curl -X POST 'https://api.aimable.com/api/v1/admin/roles' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "admin-role",
    "name": "Administrator Role"
  }'

Response (201 Created):

json
{
  "id": "role_123e4567-e89b-12d3-a456-426614174001",
  "key": "admin-role",
  "name": "Administrator Role"
}
bash
# Assign a permission to the role
curl -X POST 'https://api.aimable.com/api/v1/admin/roles/role_123e4567-e89b-12d3-a456-426614174001/permissions' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "permission_id": "perm_123e4567-e89b-12d3-a456-426614174002"
  }'

Manage a Principal (User/Service)

Principals represent actors that can be granted access.

bash
# Create a service principal
curl -X POST 'https://api.aimable.com/api/v1/admin/principals' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "service",
    "name": "Billing Service"
  }'
bash
# Generate an API key for the principal
curl -X POST 'https://api.aimable.com/api/v1/admin/principals/prin_123e4567-e89b-12d3-a456-426614174003/api-keys' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "prod-api-key",
    "scopes": ["billing:read", "billing:write"]
  }'

Common Workflows

Onboarding a New Tenant

  1. POST /v1/admin/tenants – Register the tenant.
  2. POST /v1/admin/roles – Create roles for the tenant.
  3. POST /v1/admin/principals – Register principals (users/services).
  4. POST /v1/admin/roles/{role_id}/permissions – Assign permissions.
  5. POST /v1/admin/principals/{id}/api-keys – Issue API keys.

Revoking Access

  1. POST /v1/admin/principals/{id}/api-keys/{key_id}/revoke – Revoke compromised key.
  2. PATCH /v1/admin/principals/{id} – Optionally deactivate the principal.

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

Related Endpoints

See also