Authentication

Bearer token authentication. Get a token, send it on every request, refresh when needed.

How it works

Grasshopper uses token-based auth. You exchange your API user credentials for a short-lived bearer token, then send that token on every subsequent request via the Authorization header.

Request a token

Body parameters

curl -X POST https://{licensee-url}/api/token/ \
  -H "Content-Type: application/json" \
  -d '{
    "email": "api@your-company.com",
    "password": "your-api-password"
  }'

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "rfsh_abc123...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Use the token

Include the token in the Authorization header on every subsequent request:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

Refresh a token

Tokens expire after the duration shown in expires_in (seconds). Use the refresh token to get a new access token without re-prompting for credentials.

Revoke a token

If a token is leaked or no longer needed, revoke it. Subsequent requests with that token will return 401 Unauthorized.

Security best practices

• Never commit credentials — store API user passwords in a secret manager (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault)
• Cache the token — don't request a new one for every API call. Reuse until close to expiration.
• Refresh proactively — refresh ~60s before expiration to avoid in-flight failures
• Use a server-side proxy — never expose API credentials to browser JavaScript
• Rotate periodically — request a new password from your licensee every 90 days

Common errors

See Errors for the full error reference.