# Refresh your token

`POST https://api.mailmasker.org/api/v1/auth/refresh`

Trade your refresh token for a new token and a new refresh token.

- Who can use it: Anyone, with no sign-in
- Area: Sign-in and tokens
- Answers 200 OK when it works
- Page: https://developer.mailmasker.org/refresh-token

Keeps a session going without your password. A refresh token works once: keep the new one in place of the old, and expect the token you had to stop working now. If the answer never reached you, sending the old refresh token again within a few minutes hands back the same new pair, marked `"recovered": true`.

## Parameters

| Name | In | Required | What it is | Example |
|---|---|---|---|---|
| `refresh_token` | body | yes | The refresh token from signing in, or from your last refresh. | `$REFRESH_TOKEN` |

## Good to know

- An unknown, run-out or signed-out refresh token answers 401, and so does one whose account a site admin has switched off; sign in again.
- Changing or resetting your password ends every other session's refresh token as well as its token.
- A refresh token lasts 30 days unless the server is set otherwise, so a session that refreshes at least that often never needs your password again.
- homelab-cli refreshes for you whenever its token runs out, so it has no command for this.

## Examples

cURL:

```bash
curl -s -X POST 'https://api.mailmasker.org/api/v1/auth/refresh' \
  -H 'Content-Type: application/json' \
  -d "{\"refresh_token\":\"$REFRESH_TOKEN\"}"
```

Perl:

```perl
use Mojo::Base -strict;
use Mojo::UserAgent;

my $ua  = Mojo::UserAgent->new;
my $res = $ua->post('https://api.mailmasker.org/api/v1/auth/refresh',
    json => { refresh_token => $ENV{REFRESH_TOKEN} })->result;
die $res->code, ' ', ($res->json('/error') // $res->message), "\n" unless $res->is_success;
print $res->body, "\n";
```

homelab-cli:

There is no homelab-cli command for this yet.

## Response

200 OK:

```json
{
  "success": true,
  "token": "<token>",
  "refresh_token": "<refresh token>",
  "expires_in": 86400
}
```