Authentication

The TreasuryPath API uses JWT (JSON Web Token) based authentication. To access the API, exchange your API credentials for a JWT token via the sessions endpoint, then include this token in the Authorization header of all subsequent requests.

Get JWT Token

Endpoint

POST /api/v1/sessions

Request Body

{
  "api_key": "your_api_key",
  "api_secret": "your_api_secret"
}

Response

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Parameters

Parameter	Type	Required	Description
api_key	string	Yes	Your API key from your TreasuryPath account
api_secret	string	Yes	Your API secret from your TreasuryPath account

Example Request

curl -X POST https://api.treasurypath.com/api/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "tp_key_1234567890abcdef",
    "api_secret": "tp_secret_abcdef1234567890"
  }'

Example Response

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3b3Jrc3BhY2VfaWQiOjEsImFwaV9rZXkiOiJ0cF9rZXlfMTIzNDU2Nzg5MGFiY2RlZiIsImV4cCI6MTY0MDk5NTIwMH0.signature"
  }
}

Using the JWT Token

Include the JWT token in the Authorization header of all API requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example Authenticated Request

curl -X GET https://api.treasurypath.com/api/v1/companies/123/bank_accounts \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Token Details

• Expiration: Tokens expire after 24 hours from issuance
• Security: Tokens are signed and validated for each request
• Refresh: Obtain a new token before the current one expires

Token Expiration Behavior

When a token expires or becomes invalid, the API will reject requests with a 401 Unauthorized response:

{
  "errors": [
    {
      "field": "api_key",
      "message": "Invalid or revoked API credentials"
    }
  ]
}

Important: The TreasuryPath API does not automatically refresh tokens. Your application must handle token expiration using one of these approaches:

Option 1: Reactive Refresh (Handle Expiration)

1. Detect the 401 response with the error message above
2. Request a new JWT token using your API credentials via the /api/v1/sessions endpoint
3. Retry the original request with the new token

Option 2: Proactive Refresh (Scheduled Refresh)

1. Implement a scheduled operation to refresh tokens before they expire
2. Request a new token before the 24-hour expiration (e.g., after 23 hours)
3. Replace the old token with the new one in your application
4. This prevents any request interruptions due to expired tokens

Error Responses

Invalid Credentials

{
  "errors": [
    {
      "field": "api_credentials",
      "message": "Invalid API credentials"
    }
  ]
}

Missing Parameters

{
  "errors": [
    {
      "field": "api_key",
      "message": "API key is required"
    }
  ]
}

Security Best Practices

1. Store credentials securely: Never expose API credentials in client-side code
2. Never log sensitive data: Do not log API secrets or JWT tokens in application logs, error messages, or debugging output
3. Use HTTPS: Always use secure connections
4. Reuse tokens: Avoid generating a new token for every request. Tokens are valid for 24 hours - reuse the same token across multiple requests until it expires
5. Token refresh: Obtain new tokens before expiration using one of the approaches described in Token Expiration Behavior
6. Rotate credentials: Regularly rotate your API credentials
7. Monitor usage: Track API usage for suspicious activity

Common Issues

401 Unauthorized

• Check that your API credentials are correct
• Ensure the API credentials are active in your TreasuryPath account

403 Forbidden

• Check that you're accessing resources that belong to your account
• Verify you're using the correct resource IDs in the request path

Next Steps

• API Basics - Learn fundamental API concepts including response formats and error handling
• Quick Start Guide - Complete walkthrough of your first payment with authentication examples
• Error Handling - Learn how to handle API errors effectively
• Postman Collection - Download our collection with pre-configured authentication
• FAQ - Find answers to frequently asked questions