API Authentication Guide

To access any GoFax API endpoint, every request must be authenticated using an API Token. This token uniquely identifies your account and authorises your application to interact with GoFax services.

Your API Token can be found in your GoFax account under My Account → API Access

Depending on the API version you are using, GoFax supports two different authentication methods:

• API v2.0 – Header-Based Authentication (Recommended)
• API v1.0 – Query Parameter Authentication (Legacy)
  
  

This guide also covers

• How to migrate from v1.0 to v2.0
• How to test authentication
• Error handling
• API token security

API Credentials

Treat your API Token like a password. Never share it publicly or store it in client-side code.

 Learn how to create an API token

 

1. API v1.0 – Query Parameter Authentication (Legacy)

In API v1.0, the API Token must be passed as a URL parameter named token.

This method is still supported for backward compatibility but is no longer recommended due to security limitations (tokens may appear in logs or browser history).

curl --location --request PUT 'https://restful-api.gofax.com.au/v1.0/Account/CheckHaveAccess?token=XXXXXXXXXXXXXXXXXXX' \

--header 'Accept: application/json'

 

2. API v2.0 – Header-Based API Token Authentication (Recommended)

All API v2.0 endpoints require you to include your API Token in the request header:

x-api-token: YOUR_API_TOKEN

This method is more secure and is the standard for all new GoFax integrations.

Example – cURL

curl --location --request PUT 'https://restful-api.dev.gofax.com.au/v2.0/Account/CheckHaveAccess' \
--header 'Accept: application/json' \
--header 'x-api-token: XXXXXXXXXXXXXXXXXXX'\
--header 'Authorization: ••••••'

Error Handling

If the API Token is missing, invalid, or improperly formatted, you will receive a:

HTTP 401 Unauthorised

Example JSON Response

{
"error": "UNAUTHORISED",
"message": "Token is not invalid."
}

Common Causes

• Header missing (x-api-token not provided)
• Token expired or regenerated
• Typo in the token value
• Using query parameter instead of header for v2.0
• Calling a v2.0 endpoint with a v1.0 authentication method

 

Best Practices for Securing Your API Token

🔐 Do

• Store the token using environment variables or secure vaults
• Rotate/regenerate tokens periodically
• Use HTTPS always
• Remove tokens from logs and monitoring tools

🚫 Do Not

• Embed tokens in frontend or mobile apps
• Share tokens via email or chat
• Store tokens in code repositories
• Expose tokens in URLs (except when required for legacy v1.0 endpoints)

 

Testing Authentication

You can test authentication using:

Postman

1. Go to Headers tab
2. Add: Key: x-api-token Value: YOUR_API_TOKEN
3. Send a request to a v2.0 endpoint

Sample Test Endpoint

PUT https://restful-api.gofax.com.au/v2.0/Account/CheckHaveAccess

Returns:

{
"Success": true,
"Message": "Token valid",
"ValidationErrors": null,
"Response": "XXXXXXXXXXXXXXXXXXXXXXXXXX"
}

 

Migration Guide: v1.0 → v2.0

If you are updating your integration:

Feature v1.0 v2.0

Authentication ? token= x-api-token header

To migrate:

1. Replace all v1.0 URLs with v2.0 equivalents
2. Remove ?token=
3. Add header:
4. x-api-token: YOUR_API_TOKEN
5. Update payloads to match v2.0 schema

 

If you encounter authentication issues or need assistance integrating with the GoFax API, contact GoFax support.