diff options
Diffstat (limited to 'docs/api.md')
| -rw-r--r-- | docs/api.md | 29 |
1 files changed, 29 insertions, 0 deletions
diff --git a/docs/api.md b/docs/api.md index 4957666..3545a46 100644 --- a/docs/api.md +++ b/docs/api.md @@ -8,6 +8,35 @@ On errors, the response body is freeform text and is meant to be shown to the us Requests that require a JSON body must include a `content-type: application/json` header. For requests that take a JSON body, if the body does not match the required schema, the endpoint will return a 422 Unprocessable Entity response, instead of the responses documented for that endpoint. +## Initial setup + +The `hi` service requires setup before it can enter service. This setup is performed online, via the `hi` API. Any request to an API endpoint before setup has been completed will return a 409 Conflict response, unless the endpoint is documented as allowing requests before setup. + +### `POST /api/setup` + +Performs the initial setup, creating an initial login without requiring an invite. + +This endpoint does not require an `identity` cookie. + +This endpoint can be called before initial setup. + +#### Request + +```json +{ + "name": "example username", + "password": "the plaintext password", +} +``` + +#### On success + +This endpoint returns a 204 No Content response on success, with a `Set-Cookie` header setting the `identity` cookie to a newly created token for the initial login. See the [Authentication](#Authentication) section for details on how this cookie should be used. + +#### Setup already completed + +Once performed, this operation cannot be performed a second time. Subsequent requests to this endpoint will return a 409 Conflict response. + ## Client initialization Clients will generally need some information about the session in order to present a coherent view to the user, including the session's login identity. |