Security best practices

We strongly recommend that you use these best practices to enhance the security of your interactions. While these guidelines provide a framework, you ultimately are responsible for implementing and maintaining appropriate security measures.

Managing API keys and credentials

Storing API keys

Never hardcode API keys or sensitive credentials, such as client secrets or the private key of a signing key pair, directly in your application's source code.

Instead, use secure storage mechanisms such as environment variables, dedicated secrets management services (for example, AWS Secrets Manager, Google Secret Manager, Azure Key Vault, or HashiCorp Vault), or encrypted configuration files.

Client secrets

When you generate client secrets through the TrueLayer Console, you receive a downloadable .txt file. You must handle this file securely.

Upload the client secret to your chosen secure storage mechanism, like a secrets management service, and thenpermanently delete the downloaded file from your local system, including emptying the trash or recycling bin. This minimises the risk of leaving the secret in an insecure location like a downloads folder.

Principle of least privilege

Adhere to the principle of least privilege. Grant only the minimum necessary permissions to your API keys and client secrets required for your application's functionality. Avoid using keys with excessive or broad privileges. Here's how you can do this:

Scope down permissions

If a specific API endpoint requires a specific set of scopes, ensure that your API key is restricted to only those scopes.

Role-based permissions

Assign roles to your applications or users that align with their specific functions, and ensure each role has only the permissions essential to perform its tasks.

In the Console, you can configure user roles with specific access permissions.

Time-bound access

For certain sensitive operations or troubleshooting, consider issuing temporary credentials with a limited lifespan.

Access control

Ensure that only authorised people have access to API keys and credentials. Implement strong access controls on any systems or services that store these secrets.

Regular review

Periodically review the permissions assigned to your API keys and client secrets to ensure they still align with current operational needs and remove any unnecessary privileges. Avoid using keys with excessive or broad privileges.

Network security

Configure strict outbound firewall rules on your application's hosting environment to allow connections only to trusted and known API endpoints.

IP whitelisting

If the API provider supports it, implement IP whitelisting. This restricts API access to only a predefined set of trusted IP addresses from which your applications operate.

Errors

Error messages

Implement generic and non-descriptive error messages for clients in production environments. Avoid exposing sensitive information such as stack traces, database details, or internal system configurations in error responses.

Alerting

Establish monitoring and alerting mechanisms for critical security events, such as multiple failed authentication attempts, unusual API usage patterns, or signs of unauthorised access.

Logging

Implement robust and detailed logging for all API calls, authentication attempts, errors, and other security-related events. Logs should be stored securely and be immutable. Do not log sensitive data, for example IBANs or user credentials. If Personally Identifiable Information (PII) must be logged for debugging or auditing purposes, ensure that it is properly encrypted or anonymised.

Authentication

Token management

Securely store and handle authentication tokens. Do not expose tokens in URLs, browser localStorage (if applicable), or insecure log files. Implement appropriate token expiration and refresh mechanisms.

Access control enforcement

Ensure that your application properly enforces access control based on the authenticated user's or application's authorized permissions when making API calls. Do not trust client-side assertions of authorisation.

Efficient token usage

Do not generate a new access token for every single API request. Instead, obtain an access token once and reuse it for multiple API calls until it expires.

First, exchange an authorisation code for a short-lived access_token and potentially a refresh_token. This initial exchange typically involves your client_id and client_secret.

Once you have the access_token, include it in the Authorisation header as a Bearer token for subsequent API calls. TrueLayer securely verifies JWTs, and attempts to use forged or expired tokens will result in an unauthenticated error. You do not need to send client_secrets for every API request.

Never hardcode your client_id, client_secret, or private key within your application's source code. Instead, use secure storage mechanisms like environment variables or dedicated secrets management services. After generating client secrets and downloading them, delete the downloaded file permanently.

You must also generate and set up request signing to include a Tl-Signature header with your payment requests.

Using JWT for subsequent requests

The access_token you receive is a JWT. This token should be used for all subsequent authenticated calls to any of our APIs. Reuse the access_token for multiple API calls until it expires. This minimizes the exposure of your client credentials.