Skip to main content

Migrating from Username/Password to Security Key Authentication

Updated

Overview

With our primary API, the Payment API, there are two supported methods for validating requests sent to our platform. One of these methods must be included with every request - otherwise, the request will fail and an error message will be returned.

You can authenticate using either:

  • Username and password credentials associated with a specific user on your merchant gateway account, or
  • A security key generated from within the merchant account (referred throughout this document as an API key).

While both methods are valid, using a security key is considered best practice. It offers several advantages - most importantly, it enhances the security of your integration and helps protect your merchant account.

 

 

Drawback of Using Username/Password Combination

The primary drawback of using username and password credentials in API requests is the impact on integration stability. If these credentials are ever compromised or require rotation - due to password policy changes, user deactivation, or a security incident - your integration will fail unless every reference is updated immediately. This tightly couples your API implementation to a specific user account, creating unnecessary fragility and long-term maintenance risk.

 

Example Comparison

Below are two example POST requests to the Payment API, both performing a $10 sale transaction. The only difference lies in the authentication method.

 

Using Username & Password Credentials

POST: {insert endpoint}
PARAMS: 
[
    username      : exampleUsername
    password      : examplePassword
    type          : sale
    amount        : 10
    payment_token : 2EwS2JhF-Q8TwCM-8Xbb6X-qrtjVbX46EYx
    ...
]

In this request, the merchant account’s username and password are passed via the username and password fields. These values are tied directly to a user account and must remain valid for the integration to function.

 

Using Private API Key Generated from a Merchant Account

POST: {insert endpoint}
PARAMS: 
[
    security_key  : w2b7yRSy5jKpv2Q8s32Q2EFFg9pct5re
    type          : sale
    amount        : 10
    payment_token : 8v7nb78d-ZRe9h7-WmsTJY-rNh58Wc34n8D
    ...
]

In this request, a private API key generated from within the merchant account is passed using the security_key field. This method decouples the integration from user credentials, allowing for simpler and safer key rotation when needed.

 

Risks and Operational Pitfalls of Username/Password Use

Beyond integration fragility, there are additional risks to using username/password credentials for API authentication. If the credentials are ever compromised, a malicious actor could:

  • Access the merchant portal directly – especially damaging if the compromised account has administrative privileges. They could modify other user roles or elevate their own access.
  • Run unauthorized transactions – since transaction processing is available through the portal, they could initiate payments at will.
  • View sensitive customer and business data – including personal information tied to transactions, which could be exploited or leaked.
  • Impose restrictive IP rules – effectively locking you out of your own account by limiting who can connect to the platform.

 

Why a Security Key Is a Better Approach

Even in a worst-case scenario where a security key is exposed, the consequences are more contained:

  • Security keys cannot log into the merchant portal.
  • They do not carry administrative privileges.
  • They can be quickly revoked and replaced without impacting any user accounts.
  • They are specifically designed for integration use, offering cleaner lifecycle management and reduced risk.

 

How to Tell If Your Integration Uses a Username & Password Combination

To determine whether your integration is using a username and password for API authentication, follow these steps:

  1. Check for Security Keys in Your Account
    Log in to your merchant account and navigate to:
    Options → Settings → Security Keys.
    If no security keys are listed and you know your system is actively sending API transactions, it’s very likely that your integration is using a username/password combination.
  2. Consult Your Developer or Integration Owner
    Reach out to the person or team responsible for building or maintaining your integration. Ask them to confirm whether authentication is handled using a security key or if it relies on a username and password.
  3. Contact Your Merchant Service Provider
    If you're unsure, provide a recent transaction ID from an API-based transaction to your merchant service provider. They can work with support to investigate how the request was authenticated and advise you on next steps.

 

Modifying Your Integration to Use Security Keys

If your current integration uses a username and password combination to authenticate API requests, switching to a security key is a straightforward and recommended improvement. This change enhances both the stability and maintainability of your integration. The process involves two main steps:

 

Step 1: Generate a Private Security Key with API Permissions

To begin, log into your merchant account using a user that has access to administrative options. The easiest way to confirm administrative access is to look for the “Options” section in the bottom-left corner of the portal after logging in.

  1. Navigate to:
    Options → Settings → Security Keys
  2. In the Security Keys section, click on “Add a New Private Key.”
  3. When prompted, assign the key API permissions.
  4. This will create a private security key specifically for use in your API integration.

📌 Note: Only users with administrative access will be able to generate or manage security keys.
 

 

Step 2: Update Your Integration Code

Once you’ve generated the security key, you’re ready to modify your integration. The update involves replacing the existing username/password authentication with the newly created security_key.

Here’s how to proceed:

  1. Locate the portion of your integration that constructs the final API POST request.
  2. Remove the username and password parameters from the request payload.
  3. Add a new parameter named security_key, and assign it the value of the private key you just generated.

 

Final Notes

Once the change is in place, your integration will continue to function as before - but now with a more robust and secure authentication method. Using a security key reduces fragility and simplifies future maintenance.

While this change strengthens your integration, it does not eliminate all possible security threats. We strongly recommend following broader security best practices and performing regular reviews of your integration environment.