API Reference

REST API documentation for the Riptide Application Manager. The API runs on port 11402 by default.

Live source of truth. This reference is hand-maintained and is intended to cover the most commonly-integrated endpoints with worked request/response examples. The canonical and always-current list of every endpoint, parameter, and response shape is the Swagger / OpenAPI document the API itself exposes at /swagger when Api:Swagger:Enabled=true (default off in Production for surface reduction). Endpoints documented here include the trial-user, session, role, configuration, audit-log, dashboard, application, identity-provider, and integration-related routes; the API also exposes auth (/api/auth/login, /api/auth/logout, /api/auth/refresh), security inventory (/api/security/reports), attestation key management (/api/attestation/keys), cloud events, synthetic principals, application self-registration, and other operational endpoints — see Swagger for the full surface and contracts.

Authentication

Most API requests authenticate with an API key passed in the X-Api-Key header:

curl -X GET https://<your-am-host>/api/trial-users \
  -H "X-Api-Key: rtk_your-api-key"

The interactive auth flow used by SDK applications is different — clients call POST /api/auth/login with credentials and receive a session token returned in the response body and as an HttpOnly cookie; subsequent calls include the cookie or pass the token explicitly. POST /api/auth/refresh extends an existing session without forcing a re-login, and POST /api/auth/logout invalidates it.

API keys are issued through the Application Manager Web UI. Each key is prefixed with rtk_ and can be scoped and revoked independently. Configure the service-account key in your application settings under Api:ApiKey or via the RIPTIDE_API_KEY environment variable.

Error Responses

The API uses RFC 7807 Problem Details for error responses:

{
  "type": "https://tools.ietf.org/html/rfc7807#section-3.1",
  "title": "Not Found",
  "status": 404,
  "detail": "Trial user with ID 42 was not found.",
  "traceId": "00-abc123..."
}

Health & Status

GET /health

System health check. No authentication required.

curl http://localhost:11402/health

{
  "status": "healthy",
  "timestamp": "2026-03-11T10:00:00Z",
  "service": "riptide-application-manager-api",
  "version": "1.0.0"
}

GET /api/dashboard/metrics

Dashboard metrics with trend data.

{
  "activeTrialUsers": 24,
  "totalApplications": 5,
  "activeSessions": 12,
  "trends": { }
}

GET /api/dashboard/health

Detailed system health status including database connectivity and service availability.

Trial Users

Manage trial user registration and lifecycle.

GET /api/trial-users

List trial users with optional filtering.

Query Parameters: | Parameter | Type | Description | |---|---|---| | active | boolean | Filter by active status |

Response: 200 OK

[
  {
    "id": 1,
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com",
    "isActive": true,
    "emailVerified": true,
    "trialStartDate": "2026-03-01T00:00:00Z",
    "trialEndDate": "2026-03-08T00:00:00Z",
    "createdAt": "2026-03-01T10:30:00Z"
  }
]

GET /api/trial-users/

Get a single trial user by ID.

Response: 200 OK — trial user object (same shape as list items)

Error: 404 Not Found — user does not exist

GET /api/trial-users/by-email/

Look up a trial user by email address.

Response: 200 OK — trial user object

Error: 404 Not Found — no user with that email

POST /api/trial-users

Create a new trial user.

Request Body:

{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane.doe@example.com",
  "organization": "Example Corp"
}

Response: 201 Created — created trial user object

Errors:

400 Bad Request — validation failure
409 Conflict — email already registered

PATCH /api/trial-users/

Update trial user fields.

Request Body:

{
  "firstName": "Janet",
  "isActive": false
}

Response: 200 OK — updated trial user object

DELETE /api/trial-users/

Delete a trial user.

Response: 204 No Content

Sessions

Track and manage user sessions.

GET /api/sessions

List sessions with optional filtering.

Query Parameters: | Parameter | Type | Description | |---|---|---| | userId | integer | Filter by user ID | | active | boolean | Filter by active status |

Response: 200 OK

[
  {
    "id": 1,
    "trialUserId": 1,
    "ipAddress": "192.168.1.100",
    "startedAt": "2026-03-11T09:00:00Z",
    "lastActivityAt": "2026-03-11T10:15:00Z",
    "isActive": true
  }
]

GET /api/sessions/

Get a single session by ID.

POST /api/sessions

Create a new session.

Request Body:

{
  "trialUserId": 1,
  "ipAddress": "192.168.1.100"
}

Response: 201 Created

DELETE /api/sessions/

Terminate a session (logout).

Response: 204 No Content

Roles

Manage roles and capability assignments.

GET /api/roles

List roles with optional application filtering.

Query Parameters: | Parameter | Type | Description | |---|---|---| | applicationId | integer | Filter by application |

Response: 200 OK

[
  {
    "id": 1,
    "name": "Reviewer",
    "description": "Can view and approve permits",
    "applicationId": 3,
    "capabilities": ["permits:view", "permits:approve"]
  }
]

GET /api/roles/

Get a single role by ID.

POST /api/roles

Create a new role.

Request Body:

{
  "name": "Reviewer",
  "description": "Can view and approve permits",
  "applicationId": 3,
  "capabilities": ["permits:view", "permits:approve"]
}

Response: 201 Created

PATCH /api/roles/

Update a role's name, description, or capabilities.

DELETE /api/roles/

Delete a role.

Response: 204 No Content

Configuration

Manage application configuration files with version control.

GET /api/configuration/

Get a file node by ID (metadata and content).

GET /api/configuration/tree

Get the configuration file tree for an application.

Query Parameters: | Parameter | Type | Description | |---|---|---| | applicationId | integer | Application to get the tree for |

Response: 200 OK — hierarchical file/folder structure

GET /api/configuration/

Get the version history for a configuration file.

Response: 200 OK

[
  {
    "version": 3,
    "content": "{ ... }",
    "createdAt": "2026-03-11T10:00:00Z",
    "createdBy": "admin"
  },
  {
    "version": 2,
    "content": "{ ... }",
    "createdAt": "2026-03-10T14:30:00Z",
    "createdBy": "admin"
  }
]

POST /api/configuration

Create a new file or folder in the configuration tree.

Request Body:

{
  "applicationId": 3,
  "parentId": null,
  "name": "appsettings.json",
  "type": "file",
  "content": "{ \"key\": \"value\" }"
}

Response: 201 Created

PUT /api/configuration/

Update a file's content. Automatically creates a new version.

Request Body:

{
  "content": "{ \"key\": \"updated-value\" }"
}

Response: 200 OK

POST /api/configuration/

Roll back a file to a specific version number.

Response: 200 OK — the restored file content

Audit Logs

Query the system audit trail.

GET /api/audit-logs

List audit log entries with filtering.

Query Parameters: | Parameter | Type | Description | |---|---|---| | actionType | string | Filter by action type (e.g., UserCreated, RoleUpdated) | | entityType | string | Filter by entity type (e.g., TrialUser, Role) | | userId | string | Filter by acting user | | startDate | datetime | Entries after this date | | endDate | datetime | Entries before this date |

Response: 200 OK — paginated audit log entries

GET /api/audit-logs/

Get a single audit log entry with full detail.