AimableDocs
DocsAPI Reference

Admin Tenant

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.

curl -X POST 'https://api-proxy/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):

{
  "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.

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

Response (201 Created):

{
  "id": "role_123e4567-e89b-12d3-a456-426614174001",
  "key": "admin-role",
  "name": "Administrator Role"
}
# Assign a permission to the role
curl -X POST 'https://api-proxy/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.

# Create a service principal
curl -X POST 'https://api-proxy/v1/admin/principals' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "service",
    "name": "Billing Service"
  }'
# Generate an API key for the principal
curl -X POST 'https://api-proxy/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.

Authentication and Error Handling

All endpoints require a valid access token:

Authorization: Bearer <token>

Common errors:

  • 401 Unauthorized: Missing or invalid access token.
  • 403 Forbidden: Insufficient permissions for the action.
  • 422 Unprocessable Entity: Invalid input; check detail for field-specific errors.

Example error response:

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "Field required",
      "type": "value_error.missing"
    }
  ]
}

Use these APIs to build secure, scalable tenant and access management workflows within the Aimable Platform.

Related Endpoints