Aıon

Documentation

Settings API Reference

User preferences, tenant configuration, team management, and custom S3

Session Authentication Required

All settings endpoints require active session authentication. Different endpoints require specific permissions (VIEW, ADMIN, or OWNER) as noted below.

User Settings

GET/api/v2/user/profile

Get current user profile information including preferences.

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "name": "John Doe",
  "is_active": true,
  "email_verified": true,
  "created_at": "2025-01-01T00:00:00Z",
  "last_login_at": "2025-06-10T14:22:00Z",
  "preferences": {
    "timezone": "America/New_York",
    "theme": "dark",
    "language": "en",
    "notifications": {
      "email": true,
      "browser": false
    }
  }
}
PATCH/api/v2/user/profile

Update user profile information. Allows updating name and preferences.

Request

{
  "name": "Jane Doe",
  "preferences": {
    "timezone": "Europe/London",
    "theme": "light",
    "language": "en",
    "notifications": {
      "email": true,
      "browser": true
    }
  }
}

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "name": "Jane Doe",
  "is_active": true,
  "email_verified": true,
  "created_at": "2025-01-01T00:00:00Z",
  "last_login_at": "2025-06-10T14:22:00Z",
  "preferences": {
    "timezone": "Europe/London",
    "theme": "light",
    "language": "en",
    "notifications": {
      "email": true,
      "browser": true
    }
  }
}
POST/api/v2/user/change-password

Change user password. Requires current password for verification. Rate limited to 3 requests per hour.

Request

{
  "current_password": "OldPassword123!",
  "new_password": "NewSecurePassword456!"
}

Response

{
  "message": "Password changed successfully",
  "session_rotation_required": true,
  "rotation_endpoint": "/api/v2/auth/session/rotate-session"
}
POST/api/v2/user/change-email

Request email change. Requires password verification and sends a confirmation email to the new address. Rate limited to 3 requests per day. Returns 202 Accepted.

Request

{
  "new_email": "newemail@example.com",
  "password": "CurrentPassword123!"
}

Response

{
  "message": "Email change requested. Please check your new email for verification link."
}
GET/api/v2/user/sessions

Get all active sessions for the current user. Returns a list of sessions with device and location info.

Response

[
  {
    "id": "sess_abc123",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "ip_address": "192.168.1.1",
    "created_at": "2025-06-01T08:00:00Z",
    "last_activity_at": "2025-06-10T14:22:00Z",
    "expires_at": "2025-06-15T08:00:00Z",
    "is_current": true
  },
  {
    "id": "sess_def456",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
    "ip_address": "10.0.0.50",
    "created_at": "2025-06-05T12:00:00Z",
    "last_activity_at": "2025-06-09T18:30:00Z",
    "expires_at": "2025-06-19T12:00:00Z",
    "is_current": false
  }
]
DELETE/api/v2/user/sessions/{session_id}

Revoke a specific session. Marks the session as inactive, effectively logging out that device. Returns 204 No Content on success.

Response

(No content - 204)
POST/api/v2/user/revoke-all-sessions

Revoke all sessions except the current one. Useful for security purposes when a user suspects account compromise. Returns 204 No Content on success.

Response

(No content - 204)
POST/api/v2/user/set-initial-password

Allow OAuth users to add password authentication. Enables users who signed up with OAuth (Google, GitHub, etc.) to set a password so they can sign in with either method. Returns 400 if a password is already set.

Request

"SecurePassword123!"


// Send the password directly as a JSON string body (not wrapped in an object).
// Must be at least 8 characters.

Response

{
  "success": true,
  "auth_provider": "both"
}

Tenant Settings

Permission Requirements

GET endpoints (settings, limits, members) require VIEW permission. PATCH/POST/DELETE member management endpoints require OWNER permission. PATCH tenant settings requires ADMIN role.

GET/api/v2/tenant/settings

Get current tenant settings including configuration, billing, and usage information. Requires VIEW permission.

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme Corp",
  "owner_user_id": "660e8400-e29b-41d4-a716-446655440000",
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-06-10T14:22:00Z",
  "is_active": true,
  "allowed_vlm_providers": ["openai", "anthropic", "google"],
  "allowed_domains": [],
  "max_monthly_credits": 10000,
  "max_requests_per_minute": 100,
  "custom_config": {},
  "subscription_tier": "professional",
  "subscription_expires_at": "2026-01-01T00:00:00Z",
  "current_month_credits": 2500,
  "current_month_cost": 45.00,
  "total_credits": 15000,
  "total_cost": 270.00
}
PATCH/api/v2/tenant/settings

Update tenant settings. Requires ADMIN role. Rate limited to 10 requests per minute. Note: max_monthly_credits and max_requests_per_minute are controlled by the billing system and cannot be updated here.

Request

{
  "name": "Acme Corporation",
  "allowed_vlm_providers": ["openai", "anthropic"],
  "custom_config": {
    "default_model": "gpt-4o"
  }
}

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme Corporation",
  "owner_user_id": "660e8400-e29b-41d4-a716-446655440000",
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-06-15T10:30:00Z",
  "is_active": true,
  "allowed_vlm_providers": ["openai", "anthropic"],
  "allowed_domains": [],
  "max_monthly_credits": 10000,
  "max_requests_per_minute": 100,
  "custom_config": {
    "default_model": "gpt-4o"
  },
  "subscription_tier": "professional",
  "subscription_expires_at": "2026-01-01T00:00:00Z",
  "current_month_credits": 2500,
  "current_month_cost": 45.00,
  "total_credits": 15000,
  "total_cost": 270.00
}
GET/api/v2/tenant/limits

Get tenant usage limits and current usage. Returns limits, current usage, and remaining quota. Requires VIEW permission.

Response

{
  "limits": {
    "monthly_verifications": 1000,
    "api_calls_per_minute": 100
  },
  "usage": {
    "monthly_verifications": 250,
    "api_calls_per_minute": 45
  },
  "remaining": {
    "monthly_verifications": 750,
    "api_calls_per_minute": 55
  }
}
GET/api/v2/tenant/members

List all tenant members. Returns a list of users who have access to the tenant. Requires VIEW permission.

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "admin@example.com",
    "name": "John Doe",
    "role": "owner",
    "joined_at": "2025-01-01T00:00:00Z",
    "last_active_at": null
  },
  {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "email": "editor@example.com",
    "name": "Jane Smith",
    "role": "editor",
    "joined_at": "2025-03-15T09:00:00Z",
    "last_active_at": null
  }
]
POST/api/v2/tenant/members/invite

Invite a user to join the tenant. Requires OWNER permission. Creates a new user account if the email does not exist. Rate limited to 5 requests per minute.

Request

{
  "email": "newmember@example.com",
  "role": "editor"
}

Response

{
  "id": "770e8400-e29b-41d4-a716-446655440000",
  "email": "newmember@example.com",
  "name": "newmember@example.com",
  "role": "editor",
  "joined_at": "2025-06-15T10:30:00Z",
  "last_active_at": null
}
PATCH/api/v2/tenant/members/{user_id}/role

Update a tenant member's role. Requires OWNER permission. Cannot change the owner's role. Rate limited to 10 requests per minute. Valid roles: viewer, editor, admin.

Request

{
  "role": "admin"
}

Response

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "email": "editor@example.com",
  "name": "Jane Smith",
  "role": "admin",
  "joined_at": "2025-03-15T09:00:00Z",
  "last_active_at": null
}
DELETE/api/v2/tenant/members/{user_id}

Remove a member from the tenant. Requires OWNER permission. Cannot remove the owner or yourself. Rate limited to 5 requests per minute.

Response

{
  "detail": "Member removed successfully"
}

Custom S3 Storage (BYOB)

Bring Your Own Bucket

With BYOB, your files are stored directly in your AWS S3 bucket. You maintain full control over your data. Credentials are encrypted at rest using AES-256.

POST/api/v2/tenant/s3-config

Configure custom S3 bucket for the tenant. Validates credentials by testing bucket access, then encrypts and stores them securely. Requires ADMIN permission. Rate limited to 5 requests per minute.

Request

{
  "access_key_id": "AKIAIOSFODNN7EXAMPLE",
  "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  "bucket_name": "my-company-uploads",
  "region": "us-east-1"
}

Response

{
  "configured": true,
  "bucket_name": "my-company-uploads",
  "region": "us-east-1",
  "configured_at": "2025-06-15T12:00:00Z",
  "is_validated": null,
  "error": null
}
GET/api/v2/tenant/s3-config

Get custom S3 configuration status. Returns configuration status without exposing sensitive credentials. Requires VIEW permission.

Response

{
  "configured": true,
  "bucket_name": "my-company-uploads",
  "region": "us-east-1",
  "configured_at": "2025-06-15T12:00:00Z",
  "is_validated": true,
  "error": null
}
POST/api/v2/tenant/s3-config/validate

Validate that custom S3 configuration is still working. Tests bucket access using stored credentials without modifying anything. Useful for health checks. Rate limited to 10 requests per minute.

Response

{
  "valid": true,
  "bucket_name": "my-company-uploads",
  "region": "us-east-1",
  "error": null
}
DELETE/api/v2/tenant/s3-config

Remove custom S3 configuration. After removal, all uploads will use the default Aionvision bucket. Requires ADMIN permission. Rate limited to 5 requests per minute.

Response

{
  "removed": true,
  "message": "Custom S3 configuration removed"
}

Audit Logs

Admin Access Required

Audit log endpoints require ADMIN role on the tenant.

GET/api/v2/tenant/audit-logs

Get paginated audit logs for the tenant. Supports filtering by event_type, severity, user_id, date_from, date_to, and result. Pagination via limit (1-100, default 50) and offset (default 0) query parameters.

Response

{
  "entries": [
    {
      "id": "log_abc123",
      "event_type": "auth.login",
      "event_timestamp": "2025-06-10T14:22:00Z",
      "severity": "info",
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "api_key_id": null,
      "action": "login",
      "result": "success",
      "ip_address": "192.168.1.1",
      "resource_type": null,
      "resource_id": null,
      "error_message": null,
      "metadata": {}
    }
  ],
  "total_count": 142,
  "has_more": true
}
GET/api/v2/tenant/audit-logs/{log_id}

Get a single audit log entry by ID. Requires ADMIN role on the tenant.

Response

{
  "id": "log_abc123",
  "event_type": "api_key.created",
  "event_timestamp": "2025-06-10T14:22:00Z",
  "severity": "info",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "api_key_id": null,
  "action": "create",
  "result": "success",
  "ip_address": "192.168.1.1",
  "resource_type": "api_key",
  "resource_id": "key_xyz789",
  "error_message": null,
  "metadata": {
    "key_name": "Production API Key"
  }
}

Related

Session Auth Reference

Authentication for settings access

API Keys Reference

Managing API keys