> For the complete documentation index, see [llms.txt](https://docs.truedat.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.truedat.io/v8.12/api-integrations/authentication-management/sessions.md).

# Sessions

## Check session

> Confirms that the caller's access token is still valid. Returns an empty \`200\` response with no body.\
> \
> Requires an access token.<br>

```json
{"openapi":"3.0.0","info":{"title":"td-auth","version":"Truedat 8.12.0"},"paths":{"/api/sessions":{"get":{"description":"Confirms that the caller's access token is still valid. Returns an empty `200` response with no body.\n\nRequires an access token.\n","operationId":"TdAuthWeb.SessionController.ping","parameters":[],"responses":{"200":{"description":"Session is valid"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHUnauthorizedMessageResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Check session","tags":["Sessions"]}}},"components":{"schemas":{"AUTHUnauthorizedMessageResponse":{"additionalProperties":false,"description":"Response emitted by the authentication pipeline when credentials are missing or invalid.","properties":{"message":{"description":"Error type, e.g. \"unauthorized\".","type":"string"}},"required":["message"],"title":"AUTHUnauthorizedMessageResponse","type":"object"},"AUTHInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"AUTHInternalServerErrorResponse","type":"object"}}}}
```

## Create session

> Authenticates a caller and returns a session token. The shape of the request body selects the login flow.\
> \
> \*\*Supported flows:\*\*\
> \- \*\*Password\*\* — \`{user: {user\_name, password}}\`. Verifies credentials against the local store.\
> \- \*\*Active Directory\*\* — \`{auth\_realm: "active\_directory", user: {user\_name, password}}\`.\
> \- \*\*LDAP\*\* — \`{auth\_realm: "ldap", user: {user\_name, password}}\`. The response may include \`validation\_warnings\`.\
> \- \*\*OIDC\*\* — \`{auth\_realm: "oidc", code: "...", state: "..."}\` for the callback step, or \`{auth\_realm: "oidc"}\` with a Bearer token in the \`Authorization\` header.\
> \- \*\*Auth0\*\* — \`{auth\_realm: "auth0"}\` with a Bearer token in the \`Authorization\` header.\
> \- \*\*SAML step 1\*\* — \`{SAMLResponse: "..."}\`. Returns \`302\` with a \`Location\` header pointing at \`/saml#nonce=...\`.\
> \- \*\*SAML step 2\*\* — \`{auth\_realm: "saml", nonce: "..."}\` where the nonce was issued in step 1.\
> \
> When none of the body flows matches and the request carries a \`proxy-remote-user\` header, the header value is used as the user name for proxy authentication. Proxy login is subject to the \`allow\_proxy\_login\` configuration.\
> \
> \`access\_method\` is accepted but its value is ignored. The server records the authentication method it actually uses to authenticate the caller.\
> \
> The refresh token is returned via cookie, not in the response body\
> \
> Fails with a \`401\` when credentials are invalid, the nonce is unknown/expired, or the proxy user does not exist. The body may take one of three shapes (see the response schema).<br>

```json
{"openapi":"3.0.0","info":{"title":"td-auth","version":"Truedat 8.12.0"},"paths":{"/api/sessions":{"post":{"description":"Authenticates a caller and returns a session token. The shape of the request body selects the login flow.\n\n**Supported flows:**\n- **Password** — `{user: {user_name, password}}`. Verifies credentials against the local store.\n- **Active Directory** — `{auth_realm: \"active_directory\", user: {user_name, password}}`.\n- **LDAP** — `{auth_realm: \"ldap\", user: {user_name, password}}`. The response may include `validation_warnings`.\n- **OIDC** — `{auth_realm: \"oidc\", code: \"...\", state: \"...\"}` for the callback step, or `{auth_realm: \"oidc\"}` with a Bearer token in the `Authorization` header.\n- **Auth0** — `{auth_realm: \"auth0\"}` with a Bearer token in the `Authorization` header.\n- **SAML step 1** — `{SAMLResponse: \"...\"}`. Returns `302` with a `Location` header pointing at `/saml#nonce=...`.\n- **SAML step 2** — `{auth_realm: \"saml\", nonce: \"...\"}` where the nonce was issued in step 1.\n\nWhen none of the body flows matches and the request carries a `proxy-remote-user` header, the header value is used as the user name for proxy authentication. Proxy login is subject to the `allow_proxy_login` configuration.\n\n`access_method` is accepted but its value is ignored. The server records the authentication method it actually uses to authenticate the caller.\n\nThe refresh token is returned via cookie, not in the response body\n\nFails with a `401` when credentials are invalid, the nonce is unknown/expired, or the proxy user does not exist. The body may take one of three shapes (see the response schema).\n","operationId":"TdAuthWeb.SessionController.create","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionCreateRequest"}}},"description":"Authentication request","required":false},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionTokenResponse"}}},"description":"Session token issued"},"302":{"description":"Redirect the client to the SAML exchange endpoint. The `Location` header is `/saml#nonce=<nonce>`; the client must navigate there and then call this endpoint again with `{auth_realm: \"saml\", nonce: <nonce>}`.\n","headers":{"Location":{"description":"URL the client must navigate to complete the SAML exchange.","schema":{"type":"string"},"style":"simple"}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionUnauthorizedResponse"}}},"description":"Unauthorized"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHUnprocessableEntityObjectResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Create session","tags":["Sessions"]}}},"components":{"schemas":{"SessionCreateRequest":{"description":"Authentication request. The shape of the body selects the login flow.\n\nIndependently of the body, when the `proxy-remote-user` header is present and none of the body flows matches, the endpoint falls back to **proxy login**: the header value is used as the user name.\n","oneOf":[{"$ref":"#/components/schemas/SessionPasswordRequest"},{"$ref":"#/components/schemas/SessionActiveDirectoryRequest"},{"$ref":"#/components/schemas/SessionLdapRequest"},{"$ref":"#/components/schemas/SessionOidcRequest"},{"$ref":"#/components/schemas/SessionAuth0Request"},{"$ref":"#/components/schemas/SessionSamlRequest"},{"$ref":"#/components/schemas/SessionNonceRequest"}],"title":"SessionCreateRequest"},"SessionPasswordRequest":{"additionalProperties":false,"description":"Password-based login, the most common flow.","properties":{"access_method":{"description":"Legacy field, kept for backwards compatibility.\n\n**The value sent in the request is ignored.** The server records the authentication method it actually uses to authenticate the caller.\n\nSending `\"alternative_login\"` produces no observable difference.\n","nullable":true,"type":"string"},"user":{"additionalProperties":false,"properties":{"password":{"format":"password","type":"string"},"user_name":{"type":"string"}},"required":["user_name","password"],"type":"object"}},"required":["user"],"title":"SessionPasswordRequest","type":"object"},"SessionActiveDirectoryRequest":{"additionalProperties":false,"description":"Active Directory login.","properties":{"auth_realm":{"enum":["active_directory"],"type":"string"},"user":{"additionalProperties":false,"properties":{"password":{"format":"password","type":"string"},"user_name":{"type":"string"}},"required":["user_name","password"],"type":"object"}},"required":["auth_realm","user"],"title":"SessionActiveDirectoryRequest","type":"object"},"SessionLdapRequest":{"additionalProperties":false,"description":"LDAP login. When the entry validates with warnings, the response includes them under `validation_warnings`.","properties":{"auth_realm":{"enum":["ldap"],"type":"string"},"user":{"additionalProperties":false,"properties":{"password":{"format":"password","type":"string"},"user_name":{"type":"string"}},"required":["user_name","password"],"type":"object"}},"required":["auth_realm","user"],"title":"SessionLdapRequest","type":"object"},"SessionOidcRequest":{"additionalProperties":false,"description":"OpenID Connect login. Two variants:\n\n- With `code` and `state`, for the authorization code flow callback.\n- Without `code`, using a Bearer access token in the `Authorization` header.\n","properties":{"auth_realm":{"enum":["oidc"],"type":"string"},"code":{"nullable":true,"type":"string"},"state":{"nullable":true,"type":"string"}},"required":["auth_realm"],"title":"SessionOidcRequest","type":"object"},"SessionAuth0Request":{"additionalProperties":false,"description":"Auth0 login. Requires a Bearer access token in the `Authorization` header.","properties":{"auth_realm":{"enum":["auth0"],"type":"string"}},"required":["auth_realm"],"title":"SessionAuth0Request","type":"object"},"SessionSamlRequest":{"additionalProperties":true,"description":"SAML response forwarded to the service. The payload is not processed inline: it is stored under a nonce and the endpoint responds with `302 See Other`, redirecting the client to `/saml#nonce=...`. The client completes the exchange by calling the session endpoint again with `{auth_realm: \"saml\", nonce: ...}`.\n","properties":{"SAMLEncoding":{"nullable":true,"type":"string"},"SAMLResponse":{"type":"string"}},"required":["SAMLResponse"],"title":"SessionSamlRequest","type":"object"},"SessionNonceRequest":{"additionalProperties":false,"description":"Second step of the SAML exchange. The `nonce` must match a previously stored `SAMLResponse`. Only `saml` is a valid realm: other values are rejected with `422`.\n","properties":{"auth_realm":{"enum":["saml"],"type":"string"},"nonce":{"type":"string"}},"required":["auth_realm","nonce"],"title":"SessionNonceRequest","type":"object"},"SessionTokenResponse":{"additionalProperties":false,"description":"Token issued for a successfully authenticated session.\n\n**Response body:** only `token` (and, on LDAP flows, `validation_warnings`) is returned.\n\n**Refresh token:** delivered **exclusively** through the `_td_refresh` cookie (`SameSite=Strict; Secure`). Clients must persist this cookie and send it back to `POST /api/sessions/refresh`; it is single-use.\n\n**Validity:** the access token is a signed JWT (`aud: \"truedat\"`, `iss: \"tdauth\"`). Its lifetime is configured per deployment and can be adjusted via `ACCESS_TOKEN_TTL_SECONDS`.\n","properties":{"token":{"description":"Signed JWT access token.","type":"string"},"validation_warnings":{"description":"Present only on LDAP flows. Warnings emitted while validating the LDAP entry.","items":{"type":"string"},"type":"array"}},"required":["token"],"title":"SessionTokenResponse","type":"object"},"SessionUnauthorizedResponse":{"anyOf":[{"$ref":"#/components/schemas/AUTHUnauthorizedResponse"},{"$ref":"#/components/schemas/AUTHProxyLoginDisabledResponse"},{"$ref":"#/components/schemas/AUTHLdapErrorResponse"}],"description":"Response for `401` on session endpoints.\n\nThree shapes are possible depending on the flow:\n- `%{\"errors\" => %{\"detail\" => \"Invalid credentials\"}}` — password, Active Directory, OIDC, Auth0, refresh failures.\n- `%{\"errors\" => %{\"detail\" => \"...\", \"code\" => \"proxy_login_disabled\"}}` — proxy login disabled.\n- `%{\"error\" => %{...}}` — LDAP-specific error.\n","title":"SessionUnauthorizedResponse"},"AUTHUnauthorizedResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"AUTHUnauthorizedResponse","type":"object"},"AUTHProxyLoginDisabledResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"code":{"description":"Machine-readable error code.","type":"string"},"detail":{"type":"string"}},"required":["detail","code"],"type":"object"}},"required":["errors"],"title":"AUTHProxyLoginDisabledResponse","type":"object"},"AUTHLdapErrorResponse":{"additionalProperties":false,"description":"Response emitted by the LDAP login flow on authentication failure.","properties":{"error":{"description":"LDAP error reason as reported by the identity provider.","type":"string"}},"required":["error"],"title":"AUTHLdapErrorResponse","type":"object"},"AUTHUnprocessableEntityObjectResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"AUTHUnprocessableEntityObjectResponse","type":"object"},"AUTHInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"AUTHInternalServerErrorResponse","type":"object"}}}}
```

## Destroy session

> Terminates the caller's session. Both the access token and the refresh token (if present) are deleted from the session cache. The response is empty.\
> \
> Requires an access token.<br>

```json
{"openapi":"3.0.0","info":{"title":"td-auth","version":"Truedat 8.12.0"},"paths":{"/api/sessions":{"delete":{"description":"Terminates the caller's session. Both the access token and the refresh token (if present) are deleted from the session cache. The response is empty.\n\nRequires an access token.\n","operationId":"TdAuthWeb.SessionController.destroy","parameters":[],"responses":{"204":{"description":"Session destroyed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHUnauthorizedMessageResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Destroy session","tags":["Sessions"]}}},"components":{"schemas":{"AUTHUnauthorizedMessageResponse":{"additionalProperties":false,"description":"Response emitted by the authentication pipeline when credentials are missing or invalid.","properties":{"message":{"description":"Error type, e.g. \"unauthorized\".","type":"string"}},"required":["message"],"title":"AUTHUnauthorizedMessageResponse","type":"object"},"AUTHInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"AUTHInternalServerErrorResponse","type":"object"}}}}
```

## Refresh session

> Exchanges a refresh token for a new access token. The refresh token is read from the \`\_td\_refresh\` cookie and the current access token from the \`Authorization\` header. A refresh token is single-use: after a successful exchange it cannot be reused.\
> \
> Requires both a valid access token and a valid refresh token.<br>

```json
{"openapi":"3.0.0","info":{"title":"td-auth","version":"Truedat 8.12.0"},"paths":{"/api/sessions/refresh":{"post":{"description":"Exchanges a refresh token for a new access token. The refresh token is read from the `_td_refresh` cookie and the current access token from the `Authorization` header. A refresh token is single-use: after a successful exchange it cannot be reused.\n\nRequires both a valid access token and a valid refresh token.\n","operationId":"TdAuthWeb.SessionController.refresh","parameters":[],"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionTokenResponse"}}},"description":"Session token refreshed"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionUnauthorizedResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AUTHInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Refresh session","tags":["Sessions"]}}},"components":{"schemas":{"SessionTokenResponse":{"additionalProperties":false,"description":"Token issued for a successfully authenticated session.\n\n**Response body:** only `token` (and, on LDAP flows, `validation_warnings`) is returned.\n\n**Refresh token:** delivered **exclusively** through the `_td_refresh` cookie (`SameSite=Strict; Secure`). Clients must persist this cookie and send it back to `POST /api/sessions/refresh`; it is single-use.\n\n**Validity:** the access token is a signed JWT (`aud: \"truedat\"`, `iss: \"tdauth\"`). Its lifetime is configured per deployment and can be adjusted via `ACCESS_TOKEN_TTL_SECONDS`.\n","properties":{"token":{"description":"Signed JWT access token.","type":"string"},"validation_warnings":{"description":"Present only on LDAP flows. Warnings emitted while validating the LDAP entry.","items":{"type":"string"},"type":"array"}},"required":["token"],"title":"SessionTokenResponse","type":"object"},"SessionUnauthorizedResponse":{"anyOf":[{"$ref":"#/components/schemas/AUTHUnauthorizedResponse"},{"$ref":"#/components/schemas/AUTHProxyLoginDisabledResponse"},{"$ref":"#/components/schemas/AUTHLdapErrorResponse"}],"description":"Response for `401` on session endpoints.\n\nThree shapes are possible depending on the flow:\n- `%{\"errors\" => %{\"detail\" => \"Invalid credentials\"}}` — password, Active Directory, OIDC, Auth0, refresh failures.\n- `%{\"errors\" => %{\"detail\" => \"...\", \"code\" => \"proxy_login_disabled\"}}` — proxy login disabled.\n- `%{\"error\" => %{...}}` — LDAP-specific error.\n","title":"SessionUnauthorizedResponse"},"AUTHUnauthorizedResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"AUTHUnauthorizedResponse","type":"object"},"AUTHProxyLoginDisabledResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"code":{"description":"Machine-readable error code.","type":"string"},"detail":{"type":"string"}},"required":["detail","code"],"type":"object"}},"required":["errors"],"title":"AUTHProxyLoginDisabledResponse","type":"object"},"AUTHLdapErrorResponse":{"additionalProperties":false,"description":"Response emitted by the LDAP login flow on authentication failure.","properties":{"error":{"description":"LDAP error reason as reported by the identity provider.","type":"string"}},"required":["error"],"title":"AUTHLdapErrorResponse","type":"object"},"AUTHInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"AUTHInternalServerErrorResponse","type":"object"}}}}
```