Authentication

WalletHero API supports two authentication methods: API tokens for server-to-server communication and session tokens for user-based access.

API Token Authentication (Recommended)

API tokens are long-lived tokens ideal for server-side integrations.

Obtaining an API Token

1. Log in to your WalletHero account
2. Navigate to Settings > API Token
3. Click "Generate Token"
4. Copy and securely store the token (it won't be shown again)

Or via API after logging in:

curl -X POST https://api.wallethero.app/wallethero-api/user/api-token/regenerate \
  -H "Authorization: Bearer your-session-token"

Response:

{
  "message": "API token regenerated successfully",
  "token": "abc123def456..."
}

Using the API Token

Include the token in the Authorization header:

curl https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/pass-templates \
  -H "Authorization: Bearer your-api-token"

SDK Usage

import { WalletHero } from '@wallethero/sdk';

const client = new WalletHero({
  apiToken: 'your-api-token'
});

Session Token Authentication

Session tokens are obtained through the login flow and are used for user-based access.

Login Flow

curl -X POST https://api.wallethero.app/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

Response:

{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "abc123...",
    "expires": 900000
  }
}

Refreshing Tokens

curl -X POST https://api.wallethero.app/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "abc123..."
  }'

Logout

curl -X POST https://api.wallethero.app/auth/logout \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "abc123..."
  }'

Note: /auth/login, /auth/refresh, and /auth/logout are native Directus endpoints and are not under the /wallethero-api prefix.

Token Management

Check if API Token Exists

curl https://api.wallethero.app/wallethero-api/user/api-token \
  -H "Authorization: Bearer your-session-token"

Response:

{
  "has_token": true
}

Revoke API Token

curl -X DELETE https://api.wallethero.app/wallethero-api/user/api-token \
  -H "Authorization: Bearer your-session-token"

Response:

{
  "message": "API token revoked successfully"
}

Security Best Practices

1. Never expose tokens in client-side code - API tokens should only be used server-side
2. Rotate tokens periodically - Regenerate API tokens every 90 days
3. Use environment variables - Store tokens in environment variables, not in code
4. Monitor token usage - Check for unusual API activity regularly
5. Revoke compromised tokens immediately - If a token is exposed, regenerate it right away

Error Codes

Code	Status	Description
INVALID_TOKEN	401	The provided token is invalid or expired
TOKEN_EXPIRED	401	The session token has expired
FORBIDDEN	403	Token doesn't have permission for this operation
RATE_LIMITED	429	Too many requests, please slow down