> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coverwhale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate with the Cover Whale API

# Authentication

The Cover Whale API uses token-based authentication. Submit your credentials to get an access token, then include that token in all subsequent API requests. Tokens expire after 1 hour and can be refreshed without re-entering credentials.

## Getting an Access Token

Send a `POST` request with your credentials:

```bash theme={null}
curl -X POST https://api.coverwhale.dev/v1/authentication \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "username": "your-email@example.com",
    "password": "your-password"
  }'
```

### Successful Response

```json theme={null}
{
  "AccessToken": "eyJraWQiOiJnRk5oTTh2RnRKWXVDVXU1S...",
  "RefreshToken": "eyJjdHkiOiJKV1QiLCJlbmMiOi...",
  "ExpiresIn": 3600
}
```

| Field          | Description                                                              |
| -------------- | ------------------------------------------------------------------------ |
| `AccessToken`  | Your access token. Include in the `AccessToken` header on every request. |
| `RefreshToken` | Used to get a new access token without re-entering credentials.          |
| `ExpiresIn`    | Token lifetime in seconds. Default is `3600` (1 hour).                   |

### Error Response

```json theme={null}
{
  "Error": "Auth Error: Incorrect username or password."
}
```

## Using the Access Token

Include the `AccessToken` header in every API request:

```bash theme={null}
curl -X POST https://api.coverwhale.dev/v1/indication \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "AccessToken: eyJraWQiOiJnRk5oTTh2RnRKWXVDVXU1S..." \
  -d '{ ... }'
```

<Warning>
  The header name is `AccessToken` (no space, no "Bearer" prefix). This differs from the standard `Authorization: Bearer <token>` pattern.
</Warning>

## Refreshing Tokens

When your access token expires, use the refresh token to get a new one without re-authenticating:

```bash theme={null}
curl -X POST https://api.coverwhale.dev/v1/authentication \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "username": "your-email@example.com",
    "refresh_token": "eyJjdHkiOiJKV1QiLCJlbmMiOi..."
  }'
```

This returns a new `AccessToken` and `RefreshToken`.

## Password Reset

If you need to reset your password:

### Step 1: Request a Reset Token

```bash theme={null}
curl -X GET "https://api.coverwhale.dev/v1/password-reset?username=your-email@example.com" \
  -H "Accept: application/json"
```

A reset token will be emailed to the address associated with your account.

### Step 2: Set New Password

```bash theme={null}
curl -X POST https://api.coverwhale.dev/v1/password-reset \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "username": "your-email@example.com",
    "new_password": "your-new-password",
    "reset_token": "123456"
  }'
```

## Best Practices

* **Store tokens securely** — Never expose access tokens in client-side code or logs.
* **Handle expiration** — Check for `401` responses and refresh the token automatically.
* **Rotate credentials** — Change your API password periodically.
* **One token at a time** — Each authentication call invalidates previous tokens.

## API Reference

* [Get Authentication Token](/api-reference/authentication/get-authentication-token) — Full endpoint schema
* [Get Password Reset Token](/api-reference/authentication/get-a-password-reset-token) — Request reset code
* [Reset Password](/api-reference/authentication/reset-password-with-token) — Set new password with reset code