Authentication API

Authentication and security mechanisms for the API

Authentication API

The API uses a two-layer security approach to protect your endpoints and ensure data integrity.

Overview

All API requests require two authentication mechanisms:

1. Bearer Token Authentication - OAuth 2.0 access tokens for user identification
2. HMAC Signature - Hash-based message authentication for request integrity

Authentication Flow

1. Obtain Credentials
   ↓
2. Generate Access Token (POST /v2/finance/auth-token/)
   ↓
3. Generate HMAC Signature for Request Body
   ↓
4. Make API Request with Bearer Token + HMAC in Headers

Getting Started

Step 1: Obtain Credentials

Contact us to receive your:

• client_id - Public identifier for your application
• client_secret - Confidential secret for authentication
• hmac_key - Secret key for generating HMAC signatures

🔒

Security Note: Store these credentials securely. Never expose client_secret or hmac_key in client-side code or public repositories.

Step 2: Generate Access Token

Use the Auth Token endpoint to exchange your credentials for an access token:

HTTP

POST /v2/finance/auth-token/
Content-Type: application/json

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}

Response:

JSON

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer"
}

⏰

Token Validity: Access tokens are valid for 60 minutes. Implement token refresh logic in your application.

Step 3: Generate HMAC Signature

For every API request (except token generation), you must:

1. Serialize the request body to JSON (no pretty-printing)
2. Remove unnecessary spaces (: → :, , → ,)
3. Generate HMAC-SHA512 hash using your hmac_key
4. Convert the hash to hexadecimal format

See the HMAC Documentation section for detailed implementation in multiple languages.

Step 4: Make Authenticated Requests

Include both authentication mechanisms in your request headers:

HTTP

POST /v3/{endpoint}
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "key": "value"
}

Important: HMAC signature must be included in the request headers or body (check specific endpoint documentation).

Authentication Endpoints

This section includes:

• Auth Token - Generate OAuth 2.0 access tokens
• HMAC Documentation - Comprehensive guide for implementing HMAC signatures in multiple programming languages

Security Best Practices

Credential Storage

• Never hardcode credentials in your source code
• Use environment variables or secure secret management systems
• Rotate client_secret and hmac_key regularly

Token Management

• Implement automatic token refresh before expiration
• Cache tokens to avoid unnecessary authentication requests
• Invalidate tokens immediately after detecting suspicious activity

HMAC Implementation

• Always use HMAC-SHA512 (not SHA256 or other algorithms)
• Validate the exact JSON formatting (no spaces after : and ,)
• Generate fresh signatures for every request (never reuse)

Network Security

• Always use HTTPS for API requests
• Implement certificate pinning for mobile applications
• Use TLS 1.2 or higher

Error Responses

401 Unauthorized

JSON

{
  "detail": "Invalid authentication credentials"
}

Causes:

• Invalid or expired access token
• Missing Authorization header
• Incorrect token format

403 Forbidden

JSON

{
  "detail": "Invalid HMAC signature"
}

Causes:

• Incorrect HMAC signature
• Request body modified after signature generation
• Wrong hmac_key used

Common Integration Issues

Issue: "Invalid HMAC signature" error

Solution:

1. Ensure JSON has no pretty-printing (JSON.stringify(obj) without spaces)
2. Remove spaces after : and , characters
3. Verify you're using the correct hmac_key
4. Check that request body matches the signed payload exactly

Issue: Token expires too quickly

Solution:

1. Implement proactive token refresh (e.g., refresh at 50 minutes instead of 60)
2. Cache tokens and reuse until expiration
3. Handle 401 errors gracefully with automatic re-authentication

Issue: "Missing Authorization header"

Solution:

1. Ensure header format is: Authorization: Bearer {token}
2. Include the word "Bearer" followed by a space
3. Verify token is not truncated or malformed

Testing Authentication

Postman Setup

1. Create environment variables:

   client_id: your_client_id
   client_secret: your_client_secret
   hmac_key: your_hmac_key
   access_token: (will be set automatically)

2. Add pre-request script for token management:

   JavaScript

   // Check if token is expired
   const tokenExpiry = pm.environment.get('token_expiry');
   const now = Date.now();
   
   if (!tokenExpiry || now >= tokenExpiry) {
       // Request new token
       pm.sendRequest({
           url: 'https://{environment}/v2/finance/auth-token/',
           method: 'POST',
           header: { 'Content-Type': 'application/json' },
           body: {
               mode: 'raw',
               raw: JSON.stringify({
                   client_id: pm.environment.get('client_id'),
                   client_secret: pm.environment.get('client_secret')
               })
           }
       }, (err, res) => {
           const data = res.json();
           pm.environment.set('access_token', data.access_token);
           pm.environment.set('token_expiry', now + (data.expires_in * 1000));
       });
   }

3. Add pre-request script for HMAC generation (see HMAC Documentation)

Rate Limiting

Authentication endpoints have special rate limits:

• Auth Token endpoint: 10 requests per minute per client_id
• Other endpoints: 100 requests per minute per account

Exceeding rate limits returns 429 Too Many Requests.

---

Next Steps:

• Review the Auth Token endpoint documentation
• Implement HMAC signatures using the HMAC Documentation guide
• Test your integration with the provided Postman collection