Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. See our Privacy Policy and
Terms.
openapi: 3.2.0
info:
title: qui Authentication API
description: 'qui API for managing multiple qBittorrent instances.
If allowedHosts is configured, a missing, invalid, or unlisted received Host
returns HTTP 400 before authentication or routing. X-Forwarded-Host is ignored.
Request ports do not affect matching. Only direct loopback GET and HEAD
requests to /health, /healthz/readiness, and /healthz/liveness bypass the list.
For automation create and update requests, set `conditions.category.enabled` to `true`
and `conditions.category.category` to an empty string to remove the torrent category.
Set `conditions.category.enabled` to `false` to disable the category action.'
version: 1.0.0
license:
name: GPL-2.0-or-later
url: https://opensource.org/licenses/GPL-2.0
servers:
- url: http://localhost:7476
description: Local development server
- url: /
description: Current server
security:
- ApiKeyAuth: []
- SessionAuth: []
tags:
- name: Authentication
description: User authentication and session management
paths:
/api/auth/setup:
post:
tags:
- Authentication
summary: Initial setup
description: Create the initial admin user (only available before first user is created)
security: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- username
- password
properties:
username:
type: string
minLength: 1
password:
type: string
minLength: 8
writeOnly: true
description: Password will be hashed and never returned in responses
responses:
'201':
description: Setup completed successfully
content:
application/json:
schema:
type: object
properties:
message:
type: string
user:
$ref: '#/components/schemas/User'
'400':
description: Setup already completed
'415':
description: Content-Type is not application/json
operationId: postApiAuthSetup
x-operation-id-source: derived
/api/auth/login:
post:
tags:
- Authentication
summary: Login
description: Authenticate with username and password
security: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- username
- password
properties:
username:
type: string
password:
type: string
writeOnly: true
description: Password will be hashed and never returned in responses
responses:
'200':
description: Login successful
content:
application/json:
schema:
type: object
properties:
message:
type: string
user:
$ref: '#/components/schemas/User'
'401':
description: Invalid credentials
'415':
description: Content-Type is not application/json
'429':
description: Too many failed login attempts (5 per minute, process-wide)
operationId: postApiAuthLogin
x-operation-id-source: derived
/api/auth/check-setup:
get:
tags:
- Authentication
summary: Check setup status
description: Check if initial setup is required
security: []
responses:
'200':
description: Setup status
content:
application/json:
schema:
type: object
properties:
setupRequired:
type: boolean
operationId: getApiAuthCheckSetup
x-operation-id-source: derived
/api/auth/logout:
post:
tags:
- Authentication
summary: Logout
description: End the current session
responses:
'200':
description: Logged out successfully
operationId: postApiAuthLogout
x-operation-id-source: derived
/api/auth/me:
get:
tags:
- Authentication
summary: Get current user
description: Get information about the authenticated user
responses:
'200':
description: Current user information
content:
application/json:
schema:
$ref: '#/components/schemas/User'
operationId: getApiAuthMe
x-operation-id-source: derived
/api/auth/change-password:
put:
tags:
- Authentication
summary: Change password
description: Change the current user's password
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- currentPassword
- newPassword
properties:
currentPassword:
type: string
writeOnly: true
description: Current password for verification
newPassword:
type: string
minLength: 8
writeOnly: true
description: New password will be hashed and never returned in responses
responses:
'200':
description: Password changed. Every session is ended, including the caller's.
'401':
description: Invalid current password
operationId: putApiAuthChangePassword
x-operation-id-source: derived
/api/auth/validate:
get:
tags:
- Authentication
summary: Validate session
description: Return the session's username, auth method, and profile picture. Used after the OIDC callback.
security:
- SessionAuth: []
responses:
'200':
description: Session is valid
content:
application/json:
schema:
type: object
properties:
username:
type: string
auth_method:
type: string
profile_picture:
type: string
'401':
description: Not authenticated
operationId: getApiAuthValidate
x-operation-id-source: derived
components:
schemas:
User:
type: object
properties:
id:
type: integer
username:
type: string
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: API key for authentication
ApiKeyQuery:
type: apiKey
in: query
name: apikey
description: API key via query parameter for external webhook integrations
SessionAuth:
type: apiKey
in: cookie
name: qui_user_session
description: 'Browser session cookie set by the qui web UI. POST, PUT, PATCH, and DELETE
requests authenticated by this cookie must also send an `X-Requested-With`
header. Other clients should use an API key.
'