---
title: "Create a new session (login)"
method: POST
path: "/api/session"
tags: ["Session"]
---

# Create a new session (login)

`POST /api/session`

If no users are defined, this will create an initial user with the given credentials.

## Request body

- union
  - UserPassword
    - `username` string, required — Username of the user.
    - `scope` 'admin' | 'install' | 'update' | 'read'
    - `totp_enabled` boolean — Whether two-factor authentication is enabled/required using TOTP.
    - `password` string, password, required — Password of the user.
  - object
    - `token` string — A one-time login token.

## Response `200`

Successful login

- User
  - `username` string — Username of the user.
  - `scope` 'admin' | 'install' | 'update' | 'read'
  - `totp_enabled` boolean — Whether two-factor authentication is enabled/required using TOTP.

## Other responses

- `401` — If the authentication was not successful.
- `403` — If the Contao Manager is locked after three unsuccessful login attempts.

## Changes

- **2024-11-07** `0caa21a70faf` — 2 info
  - added the new optional request property `oneOf[#/components/schemas/UserPassword]/allOf[#/components/schemas/User]/totp_enabled`
  - added the optional property `totp_enabled` to the response with the `200` status
- **2024-11-06** `e06d9f9dee25` — 2 warning, 2 info
  - removed the request property `oneOf[#/components/schemas/UserPassword]/allOf[#/components/schemas/User]/roles`
  - removed the optional property `roles` from the response with the `200` status
  - added the new optional request property `oneOf[#/components/schemas/UserPassword]/allOf[#/components/schemas/User]/scope`
  - added the optional property `scope` to the response with the `200` status
- **2024-11-02** `f68de1bd16a3` — 2 info
  - added the new optional request property `oneOf[#/components/schemas/UserPassword]/allOf[#/components/schemas/User]/roles`
  - added the optional property `roles` to the response with the `200` status
- **2023-04-24** `ded8a8d86615` — 1 warning, 1 info
  - removed `#/components/schemas/User, subschema #2` from the request body `allOf` list
  - added `#/components/schemas/UserPassword, subschema #2` to the request body `oneOf` list
- **2021-11-02** `d64a24649f97` — 1 info
  - added the non-success response with the status `403`

[Full history](https://skmtc.dev/contao/apis/contao-manager-api/changes/api/session/post.md)

---

[API](https://skmtc.dev/contao/apis/contao-manager-api.md) · [All operations](https://skmtc.dev/contao/apis/contao-manager-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/contao/contao-manager-api/revisions/f3f0ed40c70a/schema)