Exchange a username and password for a bearer token.

POST

/api/v1/auth/login

curl --request POST \
  --url https://example.com/api/v1/auth/login \
  --header 'Content-Type: application/json' \
  --data '{ "password": "example", "username": "example" }'

Takes Admin with no permission guard in front of it — unlike every other handler — because there is nothing to authenticate yet. A skeleton deployment answering 503 here is correct and not a disclosure: “there is no user store” is exactly what a would-be logger-in needs to know.

Authorizations

• None

Request Body^required

Media typeapplication/json

Login request body. Never logged, never echoed.

object

password

required

string

username

required

string

Example^generated

{
  "password": "example",
  "username": "example"
}

Responses

200

A bearer token and the role it carries

Media typeapplication/json

A freshly issued session.

object

role

required

The role it carries, so the UI can render the right navigation immediately.

string

Allowed values: viewer operator admin

token

required

The bearer token for subsequent requests.

string

Example

{
  "role": "viewer"
}

401

Incorrect username or password — one code for both, so the endpoint is not an account-enumeration oracle

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

429

Too many attempts; Retry-After carries the wait in seconds

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

503

Skeleton mode has no user store, so there is nothing to log in to

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}