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:

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

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

{
  "Error": "Auth Error: Incorrect username or password."
}

Using the Access Token

Include the AccessToken header in every API request:

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

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

Refreshing Tokens

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

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

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

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 — Full endpoint schema
Get Password Reset Token — Request reset code
Reset Password — Set new password with reset code

Getting Started

Guides

Webhooks

Authentication

Authentication

Getting an Access Token

Successful Response

Error Response

Using the Access Token

Refreshing Tokens

Password Reset

Step 1: Request a Reset Token

Step 2: Set New Password

Best Practices

API Reference

​Authentication

​Getting an Access Token

​Successful Response

​Error Response

​Using the Access Token

​Refreshing Tokens

​Password Reset

​Step 1: Request a Reset Token

​Step 2: Set New Password

​Best Practices

​API Reference

Authentication

Getting an Access Token

Successful Response

Error Response

Using the Access Token

Refreshing Tokens

Password Reset

Step 1: Request a Reset Token

Step 2: Set New Password

Best Practices

API Reference