# Authentication

```mermaid
---
Authentication states
---
stateDiagram-v2
	[*] --> Unauthenticated
	Unauthenticated --> Authenticated : /api/auth/login
	Authenticated --> Unauthenticated : /api/auth/logout
	Authenticated --> Unauthenticated : Token expired
```

Authentication associates each authenticated request with a login.


## Identity tokens

A login is primarily authenticated using its username and password. However, passwords are a sensitive, long-lived credential, and are also operationally expensive to verify; for routine access, requests are authenticated using an identity token, instead.

Tokens are issued by logging into the service, using the `/api/auth/login` endpoint. The `/api/auth/logout` endpoint immediately invalidates the token used to make a request to it. Tokens are also invalidated after seven days of inactivity.

To authenticate a request, include  `cookie: identity=TOKEN SECRET` header in the request. For browser-based clients, this may happen automatically.


## Authentication failures

Unless the endpoint's documentation says otherwise, all endpoints require authentication. Making a request to any endpoint that requires authentication, either without a token, or with a token that is not valid or that has expired, causes the service to return a `401 Unauthorized` response, instead of the responses documented for the endpoint the request was intended for. The API will not take action on requests that fail authentication in this way.


## `POST /api/auth/login`

Authenticates the user using their login name and password. The login must exist before calling this endpoint.

To create logins, see [initial setup](./initial-setup.md) and [invitations](./invitations.md).

**This endpoint does not require an `identity` cookie.**

### Request

```json
{
	"name": "example username",
	"password": "the plaintext password",
}
```

The request must have the following fields:

| Field      | Type   | Description |
|:-----------|:-------|:--|
| `name`     | string | The login's name. |
| `password` | string | The login's password, in plain text. |

### Success

<!-- This prose is duplicated by 03-initial-setup.md and in 04-invitations.md, with small changes for context. If you edit it here, edit it there, too. -->

This endpoint will respond with a status of `200 Okay` when successful. The body of the response will be a JSON object describing the authenticated login:

```json
{
	"id": "Labcd1234",
	"name": "Andrea"
}
```

The response will include the following fields:

| Field       | Type   | Description |
|:------------|:-------|:--|
| `id`        | string | The authenticated login's ID. |
| `name`      | string | The authenticated login's name. |

The response will include a `Set-Cookie` header for the `identity` cookie, providing the client with a newly-minted identity token associated with the login identified in the request. This token's value must be kept confidential.

The cookie will expire if it is not used regularly.

### Authentication failure

This endpoint will respond with a status of `401 Unauthorized` if the login name and password do not correspond to an existing login.


## `POST /api/auth/logout`

Invalidates the identity token used to make the request, logging the user out.

### Request

```json
{}
```

The request must be an empty JSON object.

### Success

This endpoint will respond with a status of `204 No Content` when successful.

The response will include a `Set-Cookie` header that clears the `identity` cookie. Regardless of whether the client clears the cookie, the service also invalidates the token.