Client Configuration

Client Configuration manages the connection between your Magento store and FreeAgent. This includes OAuth 2.0 authentication, API settings, and per-entity logging configuration.

Accessing Client Configuration

1. Log in to your Magento Admin panel
2. Navigate to Stores > Configuration
3. In the left panel, expand Byte8
4. Select FreeAgent Integration

Authentication

Client Mode

Field: mode Path: freeagent/auth/mode Type: Select Default: Production Scope: Global

Select the FreeAgent environment to connect to:

Mode	API Base URL	Purpose
Production	https://api.freeagent.com	Live accounting data
Sandbox	https://api.sandbox.freeagent.com	Testing and development

Sandbox vs Production

Always use Sandbox mode when testing or developing. Sandbox mode connects to FreeAgent's test environment and will not affect your live accounting data.

Client Name

Field: name Path: freeagent/auth/name Type: Text Default: "FreeAgent Integration" Scope: Global

A descriptive name for this FreeAgent connection. Used for identification in logs and admin panels.

Client ID

Field: client_id Path: freeagent/auth/client_id Type: Obscured (encrypted) Required: Yes Scope: Global

The OAuth Client Identifier from your FreeAgent developer app.

How to obtain:

1. Log in to FreeAgent Developer Dashboard
2. Create or select your OAuth app
3. Copy the OAuth Identifier

Client Secret

Field: client_secret Path: freeagent/auth/client_secret Type: Obscured (encrypted) Required: Yes Scope: Global

The OAuth Client Secret from your FreeAgent developer app.

How to obtain:

1. Log in to FreeAgent Developer Dashboard
2. Create or select your OAuth app
3. Copy the OAuth Secret

Authorization

After entering your Client ID and Client Secret, click Authorize to initiate the OAuth flow. This will:

1. Redirect you to FreeAgent to grant access
2. Exchange the authorization code for access and refresh tokens
3. Store the encrypted tokens in Magento's configuration

Token Management

Access tokens expire periodically. The connector automatically refreshes tokens using the stored refresh token. If token refresh fails, you will need to re-authorize.

Stored Token Fields

The following fields are managed automatically after authorization:

Field	Path	Description
Access Token	freeagent/auth/access_token	Current OAuth access token (encrypted)
Refresh Token	freeagent/auth/refresh_token	Token used to refresh access (encrypted)
Token Type	freeagent/auth/token_type	Token type, typically "bearer"
Expires In	freeagent/auth/expires_in	Access token expiration time
Refresh Token Expires In	freeagent/auth/refresh_token_expires_in	Refresh token expiration

API Settings

Connection Retry

Field: connection_retry Path: freeagent/api_config/connection_retry Type: Number Default: 2 Scope: Global

Number of retry attempts when an API request fails due to connection issues.

Recommended Values:

Environment	Retries	Reasoning
Development	1-2	Fast failure for debugging
Staging	2-3	Moderate retry for testing
Production	2-5	Robust recovery from transient errors

Connection Timeout

Field: connection_timeout Path: freeagent/api_config/connection_timeout Type: Number (seconds) Default: 0 (no timeout) Scope: Global

Maximum time in seconds to wait for a connection to be established with the FreeAgent API.

Recommended Values:

Environment	Timeout	Reasoning
Development	30	Quick feedback on connection issues
Production	60	Allow for slower connections
0 (default)	No limit	Let the system default handle it

Request Timeout

Field: request_timeout Path: freeagent/api_config/request_timeout Type: Number (seconds) Default: 0 (no timeout) Scope: Global

Maximum time in seconds to wait for a response from the FreeAgent API after connection is established.

Recommended: Set to 120 for production to prevent hanging requests.

Entity API Logging

Each entity module has an independent toggle for verbose API logging:

Contact API Logging

Field: is_api_log_enabled Path: freeagent/contact_config/is_api_log_enabled Type: Yes/No Default: No Scope: Global Log File: var/log/freeagent/contact.log

Invoice API Logging

Field: is_api_log_enabled Path: freeagent/invoice_config/is_api_log_enabled Type: Yes/No Default: No Scope: Global Log File: var/log/freeagent/invoice.log

Credit Memo API Logging

Field: is_api_log_enabled Path: freeagent/creditmemo_config/is_api_log_enabled Type: Yes/No Default: No Scope: Global Log File: var/log/freeagent/creditmemo.log

When to Enable API Logging

Enable API logging when:

• Debugging synchronization issues
• Troubleshooting API errors
• Verifying data sent/received
• During initial setup and testing

Disable in production to reduce I/O overhead and log file size.

Log Files

The connector writes to these log files:

Log File	Content
var/log/freeagent/client.log	Core API client requests, OAuth token activity
var/log/freeagent/contact.log	Contact sync operations and API calls
var/log/freeagent/invoice.log	Invoice sync operations and API calls
var/log/freeagent/creditmemo.log	Credit memo sync operations and API calls
var/log/byte8/debug.log	Core framework debug messages
var/log/byte8/scheduler.log	Profile scheduling activity

Configuration via CLI

# Set sandbox mode
bin/magento config:set freeagent/auth/mode 1

# Set production mode
bin/magento config:set freeagent/auth/mode 0

# Set connection retry attempts
bin/magento config:set freeagent/api_config/connection_retry 3

# Set request timeout (120 seconds)
bin/magento config:set freeagent/api_config/request_timeout 120

# Enable contact API logging
bin/magento config:set freeagent/contact_config/is_api_log_enabled 1

# Enable invoice API logging
bin/magento config:set freeagent/invoice_config/is_api_log_enabled 1

# View current configuration
bin/magento config:show freeagent

Troubleshooting

Authorization Fails

Problem: OAuth authorization flow fails or returns an error

Solutions:

1. Verify Client ID and Client Secret are correct
2. Check that the redirect URI in FreeAgent matches your Magento URL
3. Ensure your FreeAgent developer app is approved
4. Try sandbox mode first to verify credentials

Token Refresh Fails

Problem: API calls fail with 401 Unauthorized

Solutions:

1. Check var/log/freeagent/client.log for token refresh errors
2. Re-authorize by clicking the Authorize button
3. Verify the refresh token hasn't expired
4. Check network connectivity to FreeAgent API

Connection Timeouts

Problem: API requests time out

Solutions:

1. Increase connection_timeout and request_timeout values
2. Check server network connectivity
3. Verify FreeAgent API status
4. Review connection_retry setting

SSL Certificate Errors

Problem: SSL/TLS connection errors

Solutions:

1. Ensure PHP has the CA bundle installed
2. Update the CA certificates: update-ca-certificates
3. Check PHP openssl extension is enabled
4. Verify PHP cURL has SSL support

Security Best Practices

1. Never share credentials - Client ID and Secret are encrypted in the database
2. Use sandbox for testing - Always test in sandbox before production
3. Restrict admin access - Use Magento ACL to limit who can modify FreeAgent settings
4. Monitor logs - Review client.log for unauthorized access attempts
5. Rotate credentials - Periodically rotate OAuth credentials in FreeAgent

Next Steps

1. Profile Configuration - Configure profile settings
2. About Profiles - Set up synchronization profiles
3. Invoice Export - Configure invoice synchronization