# Authentication

The SMTP API uses JWT bearer tokens to authenticate requests. You can view and manage your API keys via the [auth API endpoints](https://docs.smtpd.dev/api/account/api-keys).

Your JWT bearer tokens carry many privileges, so be sure to keep them secure! Do not share your tokens via publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via [HTTP Basic Auth](http://en.wikipedia.org/wiki/Basic_access_authentication). Provide your API key as the basic auth username value. You do not need to provide a password. 

If you need to authenticate via bearer auth (e.g., for a cross-origin request), use `-H "Authorization: Bearer RPqH8iq9xHd7ayjQc2Qkg4j>jv/HUdWH"` instead of `-u RPqH8iq9xHd7ayjQc2Qkg4j>jv/HUdWH`.

{% hint style="info" %}
All API requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure). Calls made over plain HTTP will fail. API requests without authentication will also fail.
{% endhint %}

## Grant Token (Login)

<mark style="color:green;">`POST`</mark> `https://api.smtpd.dev/oauth/token?grant_type=password`

This endpoint allows you to login and retrieve your JWT access token & refresh token.

#### Headers

| Name          | Type   | Description                                              |
| ------------- | ------ | -------------------------------------------------------- |
| Authorization | string | `Basic: Base64(username:password) OR Base64(key:secret)` |

{% tabs %}
{% tab title="200 Existing Refresh Tokens are expired when a new Grant Token is successful. Refresh Tokens have an absolute lifespan of 30 days" %}

```
{
  "token_type": "bearer",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2NvdW50X2lkIjoiNDFkZmM2NTYtNWJmNi00YzgxLWI0ODUtZTcxMTFhNmEzMDQxIiwiZXhwIjoxNTk5MTI3OTU3LCJpZCI6IjQ4ZmFmNzEwLTc4MTgtNDk0ZC1hMjQ3LTIzZGI3MjFkNmZlYSIsImlzX2FjY291bnRfdmVyaWZpZWQiOmZhbHNlLCJpc3MiOiJTTVRQRCBJbmMiLCJuYW1lIjoiIiwic2NvcGUiOlsxXSwic3ViIjoiamFjay50cnVvbmdAamFtZXNoYXJkaWUuY29tIiwic3ViamVjdCI6ImphY2sudHJ1b25nQGphbWVzaGFyZGllLmNvbSJ9.lE0XewYrOZDCevHINLGodAQ8RJH5nSr9GnY60ZwqWfk",
  "expires_at": 1712531293539,
  "Scope": [
    "admin"
  ],
  "refresh_token": "6f4T4ws_JPkwCu9xOkul7ZkTxPyL_eB-6TFZBgITCyuV86r-yU7aF5Y4_8Y4Y7-4fzqstRDdaVX1R49ND-wkjXUMe4B3EXngkkP7sg_dP8nE7yuem3HF0sUmfVyiInhU"
}
```

{% endtab %}

{% tab title="403 " %}

```
{
  "code": 40102,
  "message": "Username and password are incorrect"
}
```

{% endtab %}
{% endtabs %}

## Refresh Access Token

<mark style="color:green;">`POST`</mark> `https://api.smtpd.dev/oauth/token?grant_type=refresh_token`

This endpoint allows you refresh your access token.

#### Request Body

| Name           | Type   | Description   |
| -------------- | ------ | ------------- |
| refresh\_token | string | Refresh Token |

{% tabs %}
{% tab title="200 " %}

```
{
  "token_type": "bearer",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2NvdW50X2lkIjoiNDFkZmM2NTYtNWJmNi00YzgxLWI0ODUtZTcxMTFhNmEzMDQxIiwiZXhwIjoxNTk5MTI4MjAzLCJpZCI6IjQ4ZmFmNzEwLTc4MTgtNDk0ZC1hMjQ3LTIzZGI3MjFkNmZlYSIsImlzX2FjY291bnRfdmVyaWZpZWQiOmZhbHNlLCJpc3MiOiJTTVRQRCBJbmMiLCJuYW1lIjoiIiwic2NvcGUiOlsxXSwic3ViIjoiamFjay50cnVvbmdAamFtZXNoYXJkaWUuY29tIiwic3ViamVjdCI6ImphY2sudHJ1b25nQGphbWVzaGFyZGllLmNvbSJ9.zUOD-Zf3mfcMF56ex5J__3KmWFNSKQrVyY5ZE28Uu3M",
  "expires_at": 1712531293539,
  "Scope": [
    "admin"
  ],
  "refresh_token": "6f4T4ws_JPkwCu9xOkul7ZkTxPyL_eB-6TFZBgITCyuV86r-yU7aF5Y4_8Y4Y7-4fzqstRDdaVX1R49ND-wkjXUMe4B3EXngkkP7sg_dP8nE7yuem3HF0sUmfVyiInhU"
}
```

{% endtab %}

{% tab title="403 " %}

```
{
  "code": 40106,
  "message": "Refresh token is invalid"
}
```

{% endtab %}
{% endtabs %}

## Revoke refresh token (Logout)

<mark style="color:green;">`POST`</mark> `https://api.smtpd.dev/oauth/revoke`

#### Headers

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

#### Request Body

| Name           | Type   | Description                 |
| -------------- | ------ | --------------------------- |
| refresh\_token | string | Refresh Token to be revoked |

{% tabs %}
{% tab title="200 " %}

```
null
```

{% endtab %}

{% tab title="401 " %}

```
{
  "code": 40106,
  "message": "Refresh token is invalid"
}
```

{% endtab %}
{% endtabs %}

## Get Me

<mark style="color:blue;">`GET`</mark> `https://api.smtpd.dev/oauth/me`

This endpoint returns the logged in users details.

#### Headers

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

{% tabs %}
{% tab title="200 " %}

```
{
  "id": "19ab52c7-da60-4dd2-af27-19f17d6afe37",
  "account_id": "811affc1-66c7-4982-b39e-29f9536b4720",
  "email_address": "jack.truong@jameshardie.com",
  "first_name": "Jack",
  "surname": "Truong",
  "gravatar_url": "",
  "is_owner": true,
  "is_verified": false,
  "created_at_utc": 1598610725000,
  "modified_at_utc": 1598610725000
}
```

{% endtab %}
{% endtabs %}