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:

API key authentication

System-to-system integrations (ERP sync, website forms, automations) can authenticate with an API key instead of a bearer token. Send the key in the X-Api-Key header; when that header is present the API uses it, otherwise it falls back to the bearer token above.

Keys are created in the app by a tenant admin under Settings → Integration → API Keys - see the User Guide for the step-by-step. Each key is scoped to a single tenant and a role (user, manager or admin), can be restricted to specific entity types, and can be given an expiry. The plain-text key is shown only once at creation.

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). Send the rowVersion you read with an update (per item in a batch, too). If the record has changed since, the API returns 409 Conflict, so you can read it again instead of overwriting someone else's change. Without rowVersion, the update changes only the fields you send, on the record as it is when saved.

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.