api keys.md

API Keys

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

Finix API requests are authenticated with API Keys. Finix uses HTTP Basic Authentication with a username:password combination. You can get API Keys for the Sandbox and Live environments from the Finix Dashboard.

Creating API Keys

To create an API Key:

Navigate to Developers > API Keys in the Finix dashboard.
Click Create API Key and enter a Display Name (can be anything).
Save the credentials somewhere secure.

Store API Keys Securely

Save your password somewhere secure. You cannot re-copy the password, but you can always create another API Key. API Keys are sensitive data and must be treated like passwords. Store them securely and only share them on an as-needed basis.

API Keys are specific to either the Sandbox or Live environments, depending on whether you get them from the Sandbox or Live Dashboard. Sandbox Keys cannot be used in the Live Environment and vice-versa. Learn more here.

API Authentication

Finix authenticates requests with HTTP Basic Authentication (RFC7617).

Create Authentication Header

All your requests will need to include the Base64-encoded Authentication header, which you can generate using your API Key username and password. Basic Authentication looks like Authorization: Basic <Base64>.

To create the Authentication header:

Combine the username and password with a colon (e.g., USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e)
Base64-encode the string (e.g., VVNzUmhzSFlaR0JQblF3OENCeUp5RVFXOjhhMTRjMmY5LWQ5NGItNGM3Mi04ZjVjLWE2MjkwOGU1YjMwZQ==)
Add the value to the Authorization Header with the Basic scheme (e.g., Authorization: Basic VVNzUmhzSFlaR0JQblF3OENCeUp5RVFXOjhhMTRjMmY5LWQ5NGItNGM3Mi04ZjVjLWE2MjkwOGU1YjMwZQ==)

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	Access
`ROLE_PLATFORM`	- Access all Applications and Merchant data (Finix Core only).\n- Gain access to every permission for any Application created with the `ROLE_PLATFORM` credentials (e.g., creating Transfers or Payment Instruments).\n- Users can create Applications, Merchants, and assign `ROLE_PARTNER` and `ROLE_MERCHANT` credentials.\n- `ROLE_PLATFORM` credentials provide Finix's highest level of access, allowing users to see and manage almost everything.
`ROLE_PARTNER`	- Access data for one Application and its Merchant data (e.g., Merchants created under the Application).\n- Gain access to `ROLE_MERCHANT` permissions for any Merchant created under the Application (e.g., creating Transfers or Payment Instruments).\n- Users can create Merchants and assign `ROLE_MERCHANT` credentials.\n- `ROLE_PARTNER` credentials offer the highest level of access available to Finix Flex customers, enabling users to investigate issues that may arise when processing payments for Merchants.
`ROLE_MERCHANT`	- Access data for one Merchant.\n- Use Finix's API freely for a single Merchant (e.g., creating Transfers or Payment Instruments).\n- `ROLE_MERCHANT` credentials are intended 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 Core customers receive ROLE_PLATFORM credentials.
Finix Flex customers receive ROLE_PARTNER credentials.

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