# Authentication

Authenticating with Couchdrops API requires a username and password and on success returns a new authentication token. This token can then we be used in subsequent API requests. Tokens generated using this route only exist for a short period of time and should not be used for long term API access. 

For long term access, create and administrative token in Couchdrop's administration interface. 

API tokens inherit the permissions of the authenticating user. 

## Authenticate with username and password

<mark style="color:green;">`POST`</mark> `https://api.couchdrop.io/authenticate`

Authenticate with a POST request

#### Request Body

| Name                                       | Type   | Description                             |
| ------------------------------------------ | ------ | --------------------------------------- |
| username<mark style="color:red;">\*</mark> | String | Username                                |
| password<mark style="color:red;">\*</mark> | String | Password                                |
| system                                     | String | An optional field describing the source |

{% tabs %}
{% tab title="200: OK Authentication succeeded" %}

```javascript
{
    "token":"<API auth token>"
}
```

{% endtab %}

{% tab title="403: Forbidden Access Denied" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="401: Unauthorized 2FA required" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}