# Sign in

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

Trade your address and password for a token and a 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/sign-in

Starts a new session. Send `token` with every other call until it runs out, `expires_in` seconds from now. Keep `refresh_token` as secret as your password: it gets you a new token without one.

## Parameters

| Name | In | Required | What it is | Example |
|---|---|---|---|---|
| `email` | body | yes | Your address. | `you@example.com` |
| `password` | body | yes | Your password. | `$PASSWORD` |

## Good to know

- A wrong address or password answers 401, and so does an account a site admin has switched off.
- After ten failed attempts from one network address within 15 minutes, it answers 429; wait 15 minutes.

## Examples

cURL:

```bash
curl -s -X POST 'https://api.mailmasker.org/api/v1/auth/login' \
  -H 'Content-Type: application/json' \
  -d "{\"email\":\"you@example.com\",\"password\":\"$PASSWORD\"}"
```

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/login',
    json => { email => 'you@example.com', password => $ENV{PASSWORD} })->result;
die $res->code, ' ', ($res->json('/error') // $res->message), "\n" unless $res->is_success;
print $res->body, "\n";
```

homelab-cli:

```bash
homelab-cli login you@example.com
```

## Response

200 OK:

```json
{
  "success": true,
  "token": "<token>",
  "refresh_token": "<refresh token>",
  "expires_in": 86400,
  "email": "you@example.com"
}
```