API Documentation

Contents

AmpleoCRM uses Keycloak (self-hosted, EU) as the identity provider via OpenID Connect (OIDC).

Web Application (Blazor UI)

The Blazor UI uses cookie-based authentication with OIDC redirect to Keycloak:

• Session cookies with 8-hour expiry (sliding)
• Login: GET /Account/Login - redirects to Keycloak
• Logout: POST /Account/Logout - signs out of cookie + Keycloak

API Authentication (Token-based)

For programmatic access (e.g., Outlook Add-in, integrations), use the token endpoint:

Login Request

Login Response

Using the Access Token

Include the access token in the Authorization header for all API requests:

Custom Claims

Keycloak tokens include custom claims used by AmpleoCRM:

Role Hierarchy

Roles are hierarchical - higher roles inherit all permissions of lower roles:

Record-Level Security

Entities that implement ownership (IOwnedEntity) enforce record-level access based on permission levels:

Tenant Isolation

All API requests are scoped to the authenticated user's tenant. Tenant isolation is enforced at 4 layers:

1. DI Context - TenantContext.TenantId set per request
2. EF Global Filters - automatic WHERE TenantId = @current on all queries
3. PostgreSQL RLS - Row-Level Security policies at the database level
4. Integration Tests - cross-tenant access verified by test suite

All entity operations use a generic REST API. Replace {entityType} with the entity system name (e.g., Company, Contact).

Base URL: /api/v1/{entityType}

Example: Create a Company

Example: List with Query Parameters

Response Format (List)

Query Parameters

Filter Operators

Filters use the format filter=fieldName:operator=value. Multiple filters can be combined.

Concurrency Control

Updates use optimistic concurrency via PostgreSQL's xmin system column (exposed as rowVersion). If the record was modified between read and update, the API returns 409 Conflict.

These endpoints allow clients to discover available entities and their schemas dynamically.

All entity mutations (create, update, delete) are automatically audited. The audit trail is read-only and append-only.

Both endpoints support page and pageSize query parameters.