POST /api/v1/session

Log in with a user name and password (SRP), and receive a bearer credential.

Authenticates by password over SRP and returns a session id in the response body.

The password is used exactly once, to mint a key-server token, and is not retained, logged or returned. Every connection the resulting session opens is built from that token.

WARNING: the session id in the body is as wide as everything the principal can reach. Unlike POST /api/v1/session/scoped it is narrowed to no object list. Anyone holding the string is that principal until it expires. Treat it exactly as you would treat the password you just presented, and do not put it in a URL.

A session obtained here is the one class on this surface that is not sender-constrained: nobody proved possession of a key, so there is nothing to bind to. Sending a DPoP header anyway is harmless.

Authentication

No session required. This operation is reachable without an Authorization header. See Authenticating.

Request

Field	Type	Required	Description
user	string	yes
password	string	yes

Example

{
  "user": "...",
  "password": "..."
}

Responses

200

Authenticated.

Field	Type	Required	Description
user	string	yes
session	string	yes	The bearer credential. Send it as Authorization: Bearer <session>.
ks	KsAddress	yes
system	SystemBlock	no	The cached boot snapshot of the key server this Gateway fronts. It carries no credential: the boot call that produces it cannot return one.
detail	string	yes

KsAddress

Field	Type	Required	Description
host	string	no
port	integer	no

Example

{
  "user": "...",
  "session": "...",
  "ks": {
    "host": "...",
    "port": 0
  },
  "system": {},
  "detail": "..."
}

400

MISSING_CREDENTIALS -- user or password was absent or empty. Note this code is NOT the surface-wide BAD_REQUEST.

401

CREDENTIALS_REJECTED (reason: credentials) -- the key server refused the name or the password. It does not say which.

403

PRINCIPAL_DISABLED -- the principal exists and is disabled.

500

A fault rather than a refusal.

OP_FAILED is the catch-all: the key server refused in words that match no classified pattern, so the Gateway cannot say more than that the operation did not happen. Some key server refusals that are conceptually a caller error arrive here rather than as a 4xx, because the wire carries no distinguishing code -- where a route can recognise one from its message it maps it, and each such mapping is documented on the operation.

503

A capacity ceiling, carrying scope and Retry-After. scope: process is this Gateway's session ceiling -- which one is named so an operator knows what to raise. Or BUILD_NOT_ADMITTED (scope: process, Retry-After): the key server does not admit this Gateway's release, so no login can be made through it -- this is never answered 401, because no credential of yours is at fault. See GET /api/v1/ready. Or CAPACITY_UNAVAILABLE (scope: process, Retry-After) -- this Gateway is at its request ceiling (see "Rate and capacity limits").

413

PAYLOAD_TOO_LARGE (retryable: false) -- the request body is larger than this deployment accepts. It was refused before it was parsed, and the connection is closed. Nothing was sent to the key server.

429

RATE_LIMITED (retryable: true, Retry-After) -- the allowance this request is charged to is spent: the login allowance of its network source (before authentication), or the allowance, the concurrency ceiling or the live-session ceiling of the identity it was verified as -- shared by every session that identity holds, including every delegated and scoped credential a service minted. It carries no scope. Nothing was sent to the key server; on a login refused after authentication, the session it created has been closed. See "Rate and capacity limits" above.

Error handling

Every failure answers JSON carrying at least code and detail. Match on code — detail is written for a human debugging the call and its wording is not part of the contract. See the error model.

Status	Meaning
400	MISSING_CREDENTIALS -- user or password was absent or empty. Note this code is NOT the surface-wide BAD_REQUEST.
401	CREDENTIALS_REJECTED (reason: credentials) -- the key server refused the name or the password. It does not say which.
403	PRINCIPAL_DISABLED -- the principal exists and is disabled.
500	A fault rather than a refusal. OP_FAILED is the catch-all: the key server refused in words that match no classified pattern, so the Gateway cannot say more than that the operation did not happen. Some key server refusals that are conceptually a caller error arrive here rather than as a 4xx, because the wire carries no distinguishing code -- where a route can recognise one from its message it maps it, and each such mapping is documented on the operation.
503	A capacity ceiling, carrying scope and Retry-After. scope: process is this Gateway's session ceiling -- which one is named so an operator knows what to raise. Or BUILD_NOT_ADMITTED (scope: process, Retry-After): the key server does not admit this Gateway's release, so no login can be made through it -- this is never answered 401, because no credential of yours is at fault. See GET /api/v1/ready. Or CAPACITY_UNAVAILABLE (scope: process, Retry-After) -- this Gateway is at its request ceiling (see "Rate and capacity limits").
413	PAYLOAD_TOO_LARGE (retryable: false) -- the request body is larger than this deployment accepts. It was refused before it was parsed, and the connection is closed. Nothing was sent to the key server.
429	RATE_LIMITED (retryable: true, Retry-After) -- the allowance this request is charged to is spent: the login allowance of its network source (before authentication), or the allowance, the concurrency ceiling or the live-session ceiling of the identity it was verified as -- shared by every session that identity holds, including every delegated and scoped credential a service minted. It carries no scope. Nothing was sent to the key server; on a login refused after authentication, the session it created has been closed. See "Rate and capacity limits" above.