API Keys

Learn how to manage your Finix API keys and submit an authenticated request.

All API requests to Finix are authenticated with your API Keys. You can not make API requests into Finix without API Credentials.

Creating API Keys

api key landing page

This screen shows you your API Keys. Click on "Create an API Key" and follow the steps to create an API Key

api key create page

Now copy the username and password and store them securely.

API Authentication

Finix uses basic authentication (RFC7617) to authenticate your requests.

All your requests will need to include the Authentication header. which is calculated by the API key's username and password.

Create Authentication Header

A Basic Authentication header looks like: Authorization: Basic [calculated credentials]

These are the instructions if you want to create the Authentication header manually. This example uses an API key with username of USsRhsHYZGBPnQw8CByJyEQW and password of 8a14c2f9-d94b-4c72-8f5c-a62908e5b30e:

Combine the username and the password with a colon.
- Result: USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Base64 encodes the resulting string.
- Result: VVNzUmhzSFlaR0JQblF3OENCeUp5RVFXOjhhMTRjMmY5LWQ5NGItNGM3Mi04ZjVjLWE2MjkwOGU1YjMwZQo=
Add this value to the Authorization header and the Basic scheme.
- Result: Authorization: Basic VVNzUmhzSFlaR0JQblF3OENCeUp5RVFXOjhhMTRjMmY5LWQ5NGItNGM3Mi04ZjVjLWE2MjkwOGU1YjMwZQo=

Sandbox and Live Keys

The Finix Keys are explicitly tied to the environment they are created in. Sandbox Keys can not be used in Live environments and vice versa

Keep API Keys Safe

Finix only shares the API Key credentials with you once. You are not able to query their value after creation.

The API Keys are sensitive data and must be treated like they are passwords. Store them securely and only let need-to-know people access their raw values.

API Key Permission Levels

When you sign up for Finix, you get a pair of credentials that you use to set up your Finix Dashboard and/or create requests with Finix's API. Due to the sensitive nature of these credentials, access is tightly controlled.

Users have three potential roles in Finix, which provide different levels of access:

Role	Permissions
ROLE_PLATFORM	Access to all `Applications` and `Merchant` data (Finix Core Only). Access every permission for any `Application` created with the ROLE_PLATFORM credentials (e.g., Create a Sale, `Identity`, `Reversal`, `Payment Instrument`, etc.). Users can create `Applications`, `Merchants` and assign ROLE_PARTNER and ROLE_MERCHANT credentials. ROLE_PLATFORM credentials are Finix's highest level of access; ROLE_PLATFORM users can see and manage almost everything.
ROLE_PARTNER	Access to the data of one `Application` and that application’s `Merchant` data (i.e., `Merchants` created under the `Application`). Access to ROLE_MERCHANT permissions for any `Merchant` created under the `Application` (e.g., Create a Sale, `Identity`, `Reversal`, `Payment Instrument`, etc.). Users can create `Merchants` and assign ROLE_MERCHANT credentials. ROLE_PARTNER credentials are the highest level of access available for Finix Flex customers; ROLE_PARTNER credentials enable you to investigate any issues that can come up when processing a `Merchants` payments.
ROLE_MERCHANT	Access to the data of one `Merchant`. Freely use Finix's API with one `Merchant` (e.g., Create a Sale, `Identity`, `Reversal`, `Payment Instrument`, etc.). ROLE_MERCHANT credentials are for your sellers; `Merchants` who use your platform to connect with buyers.

Finix ROLE_PLATFORM credentials have the highest levels of access and offer the most customization. However, more developer work is involved, and ROLE_PLATFORM users are held liable for more responsibilities like approving Settlements.

Finix Flex customers receive ROLE_PARTNER credentials.
Finix Core customers receive ROLE_PLATFORM credentials.

If you have any questions about the credentials you receive, reach out to your Finix point of contact or Finix Support.