---
updatedAt: 2026-11-12T18:17:55.000Z
agentTools:
  projectIndex: https://simpay-prod.readme.io/llms.txt
---

# Authentication API

Authentication and security mechanisms for the API

# Authentication API

The API uses a layered security approach to protect your endpoints and ensure data integrity.

## Overview

All API requests require **three authentication mechanisms**:

1. **mTLS Client Certificate** - Mutual TLS: only applications with the certificate issued for your company can connect (required from November 19, 2026). See the [mTLS Certificate](mtls-documentation) guide.
2. **Bearer Token Authentication** - OAuth 2.0 access tokens for user identification
3. **HMAC Signature** - Hash-based message authentication for request integrity

## Authentication Flow

```
0. Configure the mTLS client certificate in your HTTP client (once)
   ↓
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:**

* Request and configure your client certificate with the [mTLS Certificate](mtls-documentation) guide
* Review the [Auth Token](post_auth_token.md) endpoint documentation
* Implement HMAC signatures using the [HMAC Documentation](hmac-documentation.md) guide
* Test your integration with the provided Postman collection