Skip to main content

​
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://app.coverwhale.com/api/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
}
FieldDescription
AccessTokenYour access token. Include in the AccessToken header on every request.
RefreshTokenUsed to get a new access token without re-entering credentials.
ExpiresInToken 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://app.coverwhale.com/api/v1/getindication \
  -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://app.coverwhale.com/api/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://app.coverwhale.com/api/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://app.coverwhale.com/api/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