Sessions API

Terminal sessions into running modules. This page lists 4 operations.

Set variables in the API overview. Download OpenAPI.

Operations

Details

GET /api/v1/applications/{name}/access

What the caller may open on each instance of the application now, with the reason when not. This is the source for the interface's menu entries. Needs application.view.

Operation ID: application_access

Needs: application.view.

Example request. Replace sample names, IDs and body values with resources and settings from your installation.

curl --fail-with-body -sS -X GET "$APELORA_URL/api/v1/applications/shop/access" \
  -H "Authorization: Bearer $APELORA_TOKEN" \
  -H "Accept: application/json"

TypeScript:

const result = await client.request("application_access", { params: { name: "shop" } });

Response 200 — Done; the response holds the result..

Content-Type: application/json.

Example response from a test installation; your IDs, names and times differ.

{
  "items": [
    {
      "instance": "shop-db-01",
      "module": "db-01",
      "guestOs": "linux",
      "status": "Running",
      "kinds": [
        {
          "kind": "terminal",
          "allowed": false,
          "reason": "interactive sessions are for signed-in people",
          "approvalRequired": false
        }
      ]
    },
    {
      "instance": "shop-web-01",
      "module": "web-01",
      "guestOs": "linux",
      "status": "Running",
      "kinds": [
        {
          "kind": "terminal",
          "allowed": false,
          "reason": "interactive sessions are for signed-in people",
          "approvalRequired": false
        }
      ]
    }
  ],
  "observed": true,
  "provider": "mock",
  "idleSecs": 900,
  "maxSecs": 3600
}

Errors. The body is {"error": {"code": …, "message": …}}; see error codes for the codes every operation shares.

POST /api/v1/applications/{name}/instances/{instance}/sessions

Opens a session: checks the caller, the instance and the approval rule, and answers with a single-use ticket for the websocket. Needs instance.console (terminal, PowerShell) or instance.desktop (RDP) on the application; in production also an approval (Apelora-Approval: <id>) of instance.console on instance:<application>/<instance>.

Operation ID: open_remote_session

Needs: instance.console (terminal, PowerShell) or instance.desktop (RDP) on the application; in production also an approval (Apelora-Approval: <id>) of instance.console on instance:<application>/<instance>.

Request body (JSON):

{
  "kind": "terminal",
  "cols": 120,
  "rows": 32
}

Example request. Replace sample names, IDs and body values with resources and settings from your installation.

This request can change state. Check permissions, prerequisites and any required approval before running it.

curl --fail-with-body -sS -X POST "$APELORA_URL/api/v1/applications/shop/instances/shop-db-01/sessions" \
  -H "Authorization: Bearer $APELORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data-raw '{"kind":"terminal","cols":120,"rows":32}'

TypeScript:

const result = await client.request("open_remote_session", { params: { name: "shop", instance: "shop-db-01" }, body: { kind: "terminal", cols: 120, rows: 32 } });

Response 201 — Created; the response describes what was created..

Content-Type: application/json.

Example response from a test installation; your IDs, names and times differ.

{
  "id": "2521f680-76da-4290-bbce-c6b8739ba349",
  "ticket": "<one-time session ticket>",
  "expiresAt": "2026-10-28T23:28:10.144038Z",
  "connectPath": "/api/v1/sessions/connect",
  "protocol": "apelora.session.v1",
  "kind": "terminal",
  "instance": "shop-db-01",
  "idleSecs": 900,
  "maxSecs": 3600,
  "provider": "mock"
}

Errors. The body is {"error": {"code": …, "message": …}}; see error codes for the codes every operation shares.

GET /api/v1/sessions

Open sessions the caller started, and those on applications they may operate.

Operation ID: remote_sessions

Needs: a signed-in caller; the server decides what that caller may see.

Example request. Replace sample names, IDs and body values with resources and settings from your installation.

curl --fail-with-body -sS -X GET "$APELORA_URL/api/v1/sessions" \
  -H "Authorization: Bearer $APELORA_TOKEN" \
  -H "Accept: application/json"

TypeScript:

const result = await client.request("remote_sessions", {});

Response 200 — Done; the response holds the result..

Content-Type: application/json.

Example response from a test installation; your IDs, names and times differ.

{
  "items": []
}

Errors. The body is {"error": {"code": …, "message": …}}; see error codes for the codes every operation shares.

DELETE /api/v1/sessions/{id}

Ends a session now. Allowed for the person who has it and for whoever may operate its application. Anything else answers 404.

Operation ID: end_remote_session

Needs: a signed-in caller; the server decides what that caller may see.

Example request. Replace sample names, IDs and body values with resources and settings from your installation.

This request can change state. Check permissions, prerequisites and any required approval before running it.

curl --fail-with-body -sS -X DELETE "$APELORA_URL/api/v1/sessions/2521f680-76da-4290-bbce-c6b8739ba349" \
  -H "Authorization: Bearer $APELORA_TOKEN"

TypeScript:

await client.request("end_remote_session", { params: { id: "2521f680-76da-4290-bbce-c6b8739ba349" } });

Response 204 — Done; nothing is returned., with no body.

Errors. The body is {"error": {"code": …, "message": …}}; see error codes for the codes every operation shares.