mirror of
https://github.com/navidrome/navidrome.git
synced 2026-10-10 03:17:27 +02:00
294c1a9a6a
Adds the seven auth operations to the spec (createAccessToken, listGrants, revokeGrant and logout in core; login, setupFirstAdmin and changePassword in the password module), the bearerAuth/grantAuth schemes, and vacuum rules requiring explicit security and a known x-scope. The strict handlers sit on core/apiauth and are covered end to end against a real SQLite database. The first operations with parameters make the generated code import github.com/oapi-codegen/runtime. An oapi-codegen overlay renames the shared offset/limit parameter types, since a generated Offset clashes with Ginkgo's dot-imported Offset in this package's tests; the published spec is unchanged.
213 lines
6.7 KiB
YAML
213 lines
6.7 KiB
YAML
token:
|
|
post:
|
|
operationId: createAccessToken
|
|
x-module: core
|
|
x-stability-level: alpha
|
|
tags: [auth]
|
|
summary: Mint an access token
|
|
description: "Turns a grant into a short-lived access token, optionally narrowed to a subset of the grant's scopes. Send the grant secret as the Bearer credential."
|
|
security: [{grantAuth: []}]
|
|
requestBody:
|
|
description: Scopes to narrow the token to. Optional.
|
|
required: false
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ../components/schemas/TokenRequest.yaml
|
|
responses:
|
|
'200':
|
|
description: The new access token.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ../components/schemas/AccessToken.yaml
|
|
'400':
|
|
$ref: ../components/responses/BadRequest.yaml
|
|
'401':
|
|
$ref: ../components/responses/Unauthorized.yaml
|
|
'413':
|
|
$ref: ../components/responses/PayloadTooLarge.yaml
|
|
'500':
|
|
$ref: ../components/responses/InternalError.yaml
|
|
grants:
|
|
get:
|
|
operationId: listGrants
|
|
x-module: core
|
|
x-scope: read
|
|
x-stability-level: alpha
|
|
tags: [auth]
|
|
summary: List my grants
|
|
description: "The caller's grants, most recently used first. Grants idle long enough to have expired are not listed."
|
|
security: [{bearerAuth: []}]
|
|
parameters:
|
|
- $ref: ../components/parameters/offset.yaml
|
|
- $ref: ../components/parameters/limit.yaml
|
|
responses:
|
|
'200':
|
|
description: A page of grants.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ../components/schemas/GrantList.yaml
|
|
'400':
|
|
$ref: ../components/responses/BadRequest.yaml
|
|
'401':
|
|
$ref: ../components/responses/Unauthorized.yaml
|
|
'403':
|
|
$ref: ../components/responses/Forbidden.yaml
|
|
'500':
|
|
$ref: ../components/responses/InternalError.yaml
|
|
grant:
|
|
delete:
|
|
operationId: revokeGrant
|
|
x-module: core
|
|
x-scope: read
|
|
x-stability-level: alpha
|
|
tags: [auth]
|
|
summary: Revoke one of my grants
|
|
description: "Revokes the grant and every token minted from it. Another user's grant id answers 404."
|
|
security: [{bearerAuth: []}]
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
description: Grant id.
|
|
schema:
|
|
type: string
|
|
maxLength: 64
|
|
responses:
|
|
'204':
|
|
description: Revoked.
|
|
'400':
|
|
$ref: ../components/responses/BadRequest.yaml
|
|
'401':
|
|
$ref: ../components/responses/Unauthorized.yaml
|
|
'403':
|
|
$ref: ../components/responses/Forbidden.yaml
|
|
'404':
|
|
$ref: ../components/responses/NotFound.yaml
|
|
'500':
|
|
$ref: ../components/responses/InternalError.yaml
|
|
logout:
|
|
post:
|
|
operationId: logout
|
|
x-module: core
|
|
x-scope: read
|
|
x-stability-level: alpha
|
|
tags: [auth]
|
|
summary: Log out
|
|
description: Revokes the grant that made this request.
|
|
security: [{bearerAuth: []}]
|
|
responses:
|
|
'200':
|
|
description: Logged out.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ../components/schemas/LogoutResponse.yaml
|
|
'401':
|
|
$ref: ../components/responses/Unauthorized.yaml
|
|
'403':
|
|
$ref: ../components/responses/Forbidden.yaml
|
|
'500':
|
|
$ref: ../components/responses/InternalError.yaml
|
|
login:
|
|
post:
|
|
operationId: login
|
|
x-module: password
|
|
x-stability-level: alpha
|
|
tags: [auth]
|
|
summary: Log in with a password
|
|
description: Checks the username and password and returns a new grant. Unknown user and wrong password fail the same way.
|
|
security: []
|
|
requestBody:
|
|
description: The credentials and a description of the client.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ../components/schemas/CredentialsRequest.yaml
|
|
responses:
|
|
'200':
|
|
description: The new grant.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ../components/schemas/GrantCreated.yaml
|
|
'400':
|
|
$ref: ../components/responses/BadRequest.yaml
|
|
'401':
|
|
$ref: ../components/responses/Unauthorized.yaml
|
|
'413':
|
|
$ref: ../components/responses/PayloadTooLarge.yaml
|
|
'429':
|
|
$ref: ../components/responses/TooManyRequests.yaml
|
|
'500':
|
|
$ref: ../components/responses/InternalError.yaml
|
|
setup:
|
|
post:
|
|
operationId: setupFirstAdmin
|
|
x-module: password
|
|
x-stability-level: alpha
|
|
tags: [auth]
|
|
summary: Create the first admin
|
|
description: "Creates the first administrator while `setupRequired` is true and returns a grant for it. Answers 409 `setup_complete` once any user exists. A server with no setup step always answers 409."
|
|
security: []
|
|
requestBody:
|
|
description: The credentials and a description of the client.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ../components/schemas/CredentialsRequest.yaml
|
|
responses:
|
|
'201':
|
|
description: The admin was created.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ../components/schemas/GrantCreated.yaml
|
|
'400':
|
|
$ref: ../components/responses/BadRequest.yaml
|
|
'409':
|
|
$ref: ../components/responses/Conflict.yaml
|
|
'413':
|
|
$ref: ../components/responses/PayloadTooLarge.yaml
|
|
'429':
|
|
$ref: ../components/responses/TooManyRequests.yaml
|
|
'500':
|
|
$ref: ../components/responses/InternalError.yaml
|
|
password:
|
|
post:
|
|
operationId: changePassword
|
|
x-module: password
|
|
x-scope: password
|
|
x-stability-level: alpha
|
|
tags: [auth]
|
|
summary: Change my password
|
|
description: "Changes the caller's password. By default every other grant of the user is revoked; the calling grant survives. Answers 409 `password_managed_externally` when the password is not stored by this server."
|
|
security: [{bearerAuth: []}]
|
|
requestBody:
|
|
description: The current and the new password.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ../components/schemas/PasswordChangeRequest.yaml
|
|
responses:
|
|
'204':
|
|
description: Password changed.
|
|
'400':
|
|
$ref: ../components/responses/BadRequest.yaml
|
|
'401':
|
|
$ref: ../components/responses/Unauthorized.yaml
|
|
'403':
|
|
$ref: ../components/responses/Forbidden.yaml
|
|
'409':
|
|
$ref: ../components/responses/Conflict.yaml
|
|
'413':
|
|
$ref: ../components/responses/PayloadTooLarge.yaml
|
|
'429':
|
|
$ref: ../components/responses/TooManyRequests.yaml
|
|
'500':
|
|
$ref: ../components/responses/InternalError.yaml
|