Accounts

SESAM provides two related authentication flows:

REST API authentication uses a long-lived access token for API requests.
One-time browser login uses a short-lived, single-use ticket to establish a normal browser session.

REST API authentication

A typical API client first retrieves an access token and then sends that token in the Authorization header of its subsequent REST requests.

`POST /api/v1/accounts/login/`

Use the login endpoint to acquire an access token. Send that token with every authenticated REST request. Setting the request and response content type to application/json usually simplifies client implementations.

Using the token requires the rest_api_access feature in the plan of the account. The login endpoint itself still issues a token for every valid account, but if the current plan does not include REST API access, every request that sends the token is answered with 403 Forbidden (see Errors and limits). The check uses the plan at the time of the request, so an upgrade or downgrade takes effect immediately.

sequenceDiagram
    participant C as Client
    participant S as SESAM API
    C->>+S: POST /api/v1/accounts/login/ (username, password)
    S->>-C: authentication token ab54cd....

Example Code
import requests

with requests.Session() as session:
    data = {"username": "<username>", "password": "<password>"}
    response = session.post("https://sesam.co4e.com/api/v1/accounts/login", data=data)
    token = response.json().get("key")
    session.headers.update(
        {
            "Content-type": "application/json",
            "Accept": "application/json",
            "Authorization": f"Token {token}",
        }
    )

`POST /api/v1/accounts/logout/`

Use the logout endpoint to invalidate the access token returned by the login endpoint.

sequenceDiagram
    participant C as Client
    participant S as SESAM API
    C->>+S: POST /api/v1/accounts/logout/
    S->>-C: OK

Example Code
import requests

with requests.Session() as session:
    # ... do some work ...
    response = session.post("https://sesam.co4e.com/api/v1/accounts/logout")

Account plan, limits, and usage

`GET /api/v1/accounts/me/`

Returns the effective SESAM plan of the authenticated user together with its public capabilities, limits, and current rolling 24-hour quota usage. The endpoint accepts no user ID and always returns information for the user identified by the REST access token.

HTTP
GET /api/v1/accounts/me/
Authorization: Token <rest-api-token>
Accept: application/json

A successful response is 200 OK:

JSON
{
  "plan": {
    "name": "Basic",
    "features": {
      "projects": true,
      "rest_api": true,
      "scenario_custom_uploads": true,
      "scenario_download_as_zip": true,
      "scenario_duplication": true,
      "scenario_editor": true,
      "scenario_public_sharing": false,
      "scenario_templates": true,
      "simulation_download_outputs": true,
      "simulation_microscopic": true,
      "simulation_public_sharing": false
    },
    "limits": {
      "scenario": {
        "max_area_square_meters": 4000000,
        "max_duration_seconds": 900,
        "default_duration_seconds": 600,
        "scenario_creations_per_24h": 30,
        "custom_upload_max_bytes": 31457280
      },
      "simulation": {
        "runs_per_day": 50
      },
      "storage": {
        "retention_seconds": 432000
      }
    }
  },
  "usage": {
    "scenario_creations": {"used": 5, "limit": 30, "remaining": 25, "window_seconds": 86400},
    "simulation_runs": {"used": 17, "limit": 50, "remaining": 33, "window_seconds": 86400}
  }
}

Scenario area values are in square meters. Scenario durations and storage retention are in seconds. Upload sizes are in bytes. Quota fields cover a rolling 24-hour window and have the following meanings:

used: usage recorded by the same accounting mechanism that enforces the scenario-creation quota (custom builds, template copies and ZIP uploads together) and the simulation-run quota;
limit: maximum permitted usage in the rolling window;
remaining: unused quota, clamped to zero when usage reaches or exceeds the limit.
window_seconds: length of the rolling accounting window.

A null limit means that the value is unlimited. For an unlimited quota, both limit and remaining are null, while used still reports current usage. SESAM never reports -1 for an unlimited value.

plan.limits.storage.retention_seconds is the plan's guaranteed retention period. A null value means unlimited retention. Internal cleanup grace periods are operational details and are not included in this value.

The feature booleans indicate whether the corresponding capability is available to the account. A request without valid REST authentication receives 401 Unauthorized. A request with a token, OAuth or MCP credential of an account whose plan does not include REST API access receives 403 Forbidden (the browser session is not affected).

Some public names differ from the internal plan feature names. The key features.rest_api reports the plan feature rest_api_access, and features.simulation_download_outputs reports simulation_download_outputs_as_zip. The limits.simulation.runs_per_day key is historic: it is the number of simulation runs in the rolling 24-hour window (the same value as usage.simulation_runs.limit), not per calendar day. The keys are stable; clients must not expect additional ones, and the MCP schema rejects unknown keys.

One-time browser login lets an authenticated integration such as Baustellenatlas open SESAM in a new browser window without asking the user to log in manually. It consists of two endpoints:

The integration creates a browser login ticket through the authenticated REST API.
The browser opens the returned URL and redeems the ticket as a top-level navigation.

The ticket is valid for 120 seconds and can be redeemed exactly once. Successful redemption establishes a normal SESAM browser session; the ticket is not a replacement for the REST API access token.

`POST /api/v1/accounts/browser-login-tickets/`

Creates a browser login ticket and returns the URL used to redeem it.

The request requires normal SESAM REST token authentication and a plan with the rest_api_access feature:

HTTP
POST /api/v1/accounts/browser-login-tickets/
Authorization: Token <rest-api-token>
Content-Type: application/json

{
  "target_path": "/analyzer/12/34"
}

target_path must start with exactly one /, be a local path without a scheme, host, fragment, or backslash redirect variant, and resolve to an existing Django route. Query parameters are preserved. The browser login route itself cannot be used as a target. The target determines only the first page displayed after login: it does not grant access to the referenced object and is not an authorization scope. Existing ownership checks continue to apply.

A successful response is 201 Created:

JSON
{
  "expires_at": "2026-08-11T12:02:00Z",
  "login_url": "https://sesam.example/accounts/browser-login/?ticket=PLACEHOLDER_ONE_TIME_BROWSER_LOGIN_TICKET"
}

The origin of login_url is environment-specific. The clear-text ticket is returned only in this creation response; SESAM stores only its SHA-256 hash.

Treat login_url as a temporary sensitive credential. Do not log it, store it permanently, include it in monitoring or analytics, or attempt to reuse it. Opening it in a browser profile that already has a SESAM session changes the shared SESAM session used by other tabs in that profile.

The response includes Cache-Control: no-store and Pragma: no-cache. Relevant creation responses are:

Status	Meaning
`201 Created`	Ticket created successfully
`400 Bad Request`	Invalid or missing `target_path`
`401 Unauthorized`	Missing or invalid REST authentication
`403 Forbidden`	User does not have `rest_api_access`

Browser JavaScript must call this endpoint from an origin approved by the SESAM CORS policy.

`GET /accounts/browser-login/?ticket=<ticket>`

Open the returned login_url as a top-level browser navigation. The redemption endpoint does not require CORS. It accepts only the ticket value; the redirect destination was already validated and stored when the authenticated client created the ticket.

Successful redemption consumes the ticket, establishes a normal SESAM browser session, and redirects to the stored target_path without including the ticket in the destination URL. The resulting session follows the normal session settings and is not restricted to target_path.

Missing, malformed, expired, consumed, inactive-user, and no-longer-entitled tickets all receive the same generic 400 Bad Request response without establishing a session.

Redemption responses include Cache-Control: no-store, Pragma: no-cache, and Referrer-Policy: no-referrer.

Production operators must keep the ticket query parameter out of every reverse-proxy, load-balancer, monitoring, and APM log.