Skip to main content

POST /api/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/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​

FieldTypeRequiredDescription
userstringyes
passwordstringyes

Example

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

Responses​

200​

Authenticated.

FieldTypeRequiredDescription
userstringyes
sessionstringyesThe bearer credential. Send it as Authorization: Bearer <session>.
ksKsAddressyes
systemSystemBlocknoThe cached boot snapshot of the key server this Gateway fronts. It carries no credential: the boot call that produces it cannot return one.
detailstringyes

KsAddress

FieldTypeRequiredDescription
hoststringno
portintegerno

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.

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.

StatusMeaning
400MISSING_CREDENTIALS -- user or password was absent or empty. Note this code is NOT the surface-wide BAD_REQUEST.
401CREDENTIALS_REJECTED (reason: credentials) -- the key server refused the name or the password. It does not say which.
403PRINCIPAL_DISABLED -- the principal exists and is disabled.
500A 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.
503A 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.