### Exchange a refresh token

`POST /api/v1/auth/refresh`

Issues a new session token from a refresh token. Only available when the original login asked for one.

- Authentication: none
- Rate limit bucket: `refresh`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `refresh_token` | body | string | yes | The refresh token returned by login. Shown once; only its hash is stored. |

#### Request

```json
{
  "refresh_token": "wA7k2Jd9..."
}
```

#### Errors

| Code | Status | When |
| --- | --- | --- |
| `ERR_UNAUTHORIZED` | 401 | the session was signed out (session_revoked), or the token is unknown or expired (invalid_credentials) |

#### Note

An expired refresh token and an unknown one answer identically, on purpose. A revoked session is the one case that is distinguished, because the remedy differs: sign in again rather than retry.