An API key is a credential that identifies an account. It authenticates the owner's identity and determines their associated system user, role, and permissions.

An API key is a pair of credentials, the clientId and the client secret Together, they identify and authenticate a specific account for its system user, role, and permissions. The API key is used to obtain API tokens, which are then used to authenticate API requests.

A partner or merchant account only needs an API key if its application integrates needs to make API calls. The number of API keys is determined by the partner or merchant. A single API key for each account is typically sufficient. An API key can be replaced if it is compromised or as a routine security change.

The clientId is part of the API key that is safe to expose in frontend code. It only identifies the account. It does not grant privileged or authentication access to the account. The clientId will be visible in your API keys list of your Merchant dashboard. It will also be associated with a friendly name to make it easier to identify.

The client secret is part of the API key that is secret. It must be protected in the same way as a password.

Flute uses two types of API keys: Partner and merchant. Different types of API keys are not interchangeable between partner and merchant use. That is, a partner API key may not be used to create a merchant API token. And a merchant API key may not be used to create a partner API token. Neither are merchant API keys interchangeable among merchants. Each API key is created for a specific merchant. even if they belong to the same partner.

API keys can be deleted. This deletion may be part of a periodic key rotation depending on your security procedure requirements. We recommend deleting an API key if you suspect that the client secret is compromised. In either case, a new API key can be created.

Any applications or systems relying on the deleted API key will no longer be able to authenticate or access the API resources. API tokens that are created from the deleted API key will immediately become invalid, and, so, will have endpoint calls fail. If a new API key has been created, it must be re-entered into those applications or systems for them to run again properly. API tokens must use the new API key, too.

A partner account is used by businesses that integrate with Flute and manage one or more merchant accounts. This is in contrast to a merchant account that represents an individual business that processes payments. In other words, a partner account is never directly involved with transactions.

A partner is allowed to create API keys. The intent of partner API keys is to manage merchant API keys for merchants assigned to them. This management includes creating and deleting merchant API keys.

A partner API key can obtain API tokens (sometimes called an access token) that are used to make specified endpoint calls. These are limited to the Merchant API Keys endpoint group. This is the endpoint group that manages merchant API keys. In fact, endpoints in this group can only be called using API tokens obtained from a partner API key. Merchant API keys may not be used with endpoints in this group. The documentation will point out endpoints requiring specific API token types.

Partner API keys may be managed through the Flute dashboard. This includes creating and deleting API keys. Partner accounts can create merchant API keys for their associated merchant accounts. If you have a partner account, for more information about how to manage the API keys for the merchant accounts, see Partner API Integration.

After registering a Flute account, a partner API key must be created. Partner API keys may be managed only through the dashboard. They cannot be managed through the API suite.

To create partner API keys:

1. Log in to the Flute dashboard . This also allows you to create a new account.
2. Select Developer.
3. Select API Keys. This activates the New API Key button.
4. Select New API Key. The New API Key dialog displays.
5. Enter an API key name. This is a friendly, free-formed name. Use a meaningful name that easily identifies the API key. We suggest using the word partner in the name to allow specific identification later.
6. Select Generate Key. The clientId and client secret values display. Copy client secret to a secure location before dismissing the dialog.

Partner API keys may also be deleted using the dashboard.

An API key may be deleted.

1. Log in to the Flute dashboard . This also allows you to create a new account.
2. Select Developer.
3. In the Partner API keys section, select the trash can icon for the selected API key.

A merchant account is used by a business that represents an individual business that processes payments. This is in contrast to a partner account that only manages merchants.

Merchant API keys may be managed by either the merchant or the partner. The intent of merchant API keys is to be able to make API calls. A merchant API key is one issued specifically to individual merchant rather than a partner.

A merchant API key can obtain API tokens (sometimes called an access token) that are used to make specified endpoint calls. These API tokens may be used with most API endpoints. The documentation will point out endpoints requiring specific API token types.

After creating a new Flute account, one merchant account is automatically created. Merchant accounts may be managed through the dashboard.

Merchant API keys can be managed for each merchant account. This includes creating new API keys or deleting existing ones. Merchant API keys are managed in one of two ways:

• Through the Flute dashboard
• Programmatically using a partner API key through the Merchant API Keys endpoint group

To create merchant API keys through the Flute dashboard:

1. Log in to the Flute dashboard . This also allows you to create a new account.
2. Select Merchants. The Merchant Accounts displays.
3. Select a merchant.
4. In the navigation panel on the right, select API Keys. This activates the New API Key button.
5. Select Impersonate Merchant.
6. Select Developer in the left navigation panel.
7. Select New API Key. The New API Key dialog displays.
8. Enter an API key name. This is a friendly, free-formed name. Use a meaningful name that easily identifies the API key. We suggest using the word merchant in the name to allow specific identification later.
9. Select Generate Key. The clientId and client secret values display. Those are the two OAuth 2.0 client credential components and will be used to generate API tokens.
10. From the user identifier in the right top corner, select Stop Impersonating.

After saving the client secret in a secure location, close this dialog. The new API key displays in the dashboard section.

An API key may be deleted.

1. Log in to the Flute dashboard . This also allows you to create a new account.
2. Select Developer.
3. In the Merchant API keys section, select the trash can icon for the selected API key.

An API token is a short-lived token that is generated using an API key. It is used as an authorization credential to authenticate API requests to the Flute API endpoints.

To create an API token, in the API reference guide see API Tokens

The following is a list of terms and definitions.

An API key is a set of credentials issued to an application or account. For each application or account, it uniquely identifies and authorizes API access. An API key is composed of two values, the clientId and the client secret. The clientId is a public-facing value. It may be used in front end applications. The client secret is restricted. It must be treated like a password. The API key is used to create API tokens.

An application or account is not required to have an API key. An API key is required only if application or account needs to integrate with the API suite. The number of API keys is determined by the partner. One API key can be created for all the partner's accounts. Alternatively, multiple API keys can be created, each for a different application or account Otherwise, different API keys are not interchangeable among other partners and merchants.

The values of an individual API key component do not change. Each API key may be kept for as long as needed. An API key may be rotated as required by the partner security guidelines or if the API key has been compromised. API keys may be deleted as needed and replaced with a new API key.

An API token is a temporary credential generated by an authentication process. This is an encrypted string although it must still be protected from being displayed publicly.

It is typically generated before each endpoint use and is passed in through as an endpoint's header value. The process uses the API key's clientId and the client secret. Once created, it authenticates the caller and authorizes API access. It has an expiry date and can eventually expire. A partner can refresh the token to avoid expiration or create a new API token as needed.

API credentials is a reference to the collective set of all information used for authenticate and authorization. It includes the API key, clientId, client secret, API token, and the username and password.