Sign in
auth

Local password login; mints a CLI or browser session artifact.

Changed on

The local floor (human-auth ADR § Lockout and the local floor), which an installation may never remove. Verifies an Argon2id password verifier inside the instance-wide admission budget; an unknown account traverses a bounded dummy-verifier path so timing is comparable and no pre-authentication path distinguishes an existing account from a missing one.

Mints the artifact the request asks for. Both are distinct types with their own storage, lifetime, audit identity and revocation surface, and neither value is ever re-retrievable:

  • CLI session (default): a replayable bearer credential returned in the response body, presented on Authorization: Bearer.
  • Browser session: delivered ONLY on the __Host-hikyo HttpOnly cookie, never in the body, so injected same-origin script cannot read it. Its synchronizer token rides the __Host-hikyo-csrf companion cookie and must be echoed on the X-Hikyo-CSRF header for every state-changing cookie-authenticated request.

See /api/v1/meta for which protocol flows an instance actually offers.

post/api/v1/auth/local/login

Request

  • Base URL: / (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /api/v1/auth/local/login
  • Auth: none required

Request body

usernamestring required
passwordstring required
artifact'cli' | 'browser'

Which session artifact to mint. Omitted or cli mints a CLI session whose token is returned in the body. browser mints a browser session delivered ONLY on the __Host-hikyo cookie, with its synchronizer token on the __Host-hikyo-csrf cookie; the body then carries no token at all. The two artifacts have distinct lifetimes, distinct CSRF contracts and distinct revocation surfaces, so the caller states which one it is asking for rather than the server guessing from a header.

Response

Session minted. The token is displayed once and never again.

session_tokenstring

The bearer value, returned exactly once. A replayable credential: cookie attributes constrain browsers, not an attacker holding the value, which is why lifetimes are short and revocation is a delete. OMITTED for a browser-artifact session: that token is delivered ONLY on the __Host-hikyo HttpOnly cookie so injected same-origin script cannot read it. A CLI-artifact session, which has no cookie channel, still carries it here.

Changes

  • 54b2780eec85Revision changes
    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

  • f84a1cd8a05aRevision changes
    • warning

      added the new payload_too_large enum value to the / response property for the response status

    • warning

      added the new payload_too_large enum value to the / response property for the response status

    • warning

      added the new payload_too_large enum value to the / response property for the response status

    • warning

      added the new payload_too_large enum value to the / response property for the response status

    • warning

      added the new payload_too_large enum value to the / response property for the response status

    • warning

      added the new unprocessable enum value to the / response property for the response status

    • warning

      added the new unprocessable enum value to the / response property for the response status

    • warning

      added the new unprocessable enum value to the / response property for the response status

    • warning

      added the new unprocessable enum value to the / response property for the response status

    • warning

      added the new unprocessable enum value to the / response property for the response status