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.

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")

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 has_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 `has_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.