Sign-in and tokens

Refresh your token

POST/api/v1/auth/refresh

Who can use this: Anyone, with no sign-inAs Markdown

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	Where	What it is
refresh_token required	body	The refresh token from signing in, or from your last refresh.e.g. $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.

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

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";

There's no homelab-cli command for this yet.

Response 200 OK

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