Authentication

The Silverflow API requires authentication on all endpoints and methods. The API supports two distinct authentication schemes.

API Key

The primary method of authenticating to the Silverflow API is through API keys. API keys can be created by calling the Create API Key endpoint. You can create up to 40 API keys and update and delete them, allowing for credential rotation.

The Agent Activation process will generate an initial API Key for you. Please take a look at Activate Agent. A call to the Create API Key endpoint will return the following structure:

Necessary: The secret is only returned once in response to the createApiKey call.

Once created, the key and secret fields from the API key must be used in the HTTP Authorization header using the Basic scheme. The Basic scheme requires a username and password to be specified, separated by a colon (:) and Base64 encoded. Use the following values from the API key to construct a Basic authentication header:

Basic field	API key field	Example
username	`key`	`apk-1wtRxni5IsPsSpBLWpwr`
password	`secret`	`FWtnOOHAjbD6rNxWWEeVOCj7JXSEPGJQ`

In pseudo-code, a valid HTTP Basic Authentication header would be constructed as follows:

Using the values from the example, a valid HTTP request would look like the following:

More information on the Basic scheme can be found in RFC-7617 - The 'Basic' HTTP Authentication Scheme.

Security Scheme Type: HTTP

HTTP Authorization Scheme: basic

Bearer Token

Bearer tokens are temporary security credentials that can be used to authorize 'third parties' (bearers) access to the Silverflow API on behalf of the agent. These tokens are created by calling the Create Agent Bearer Token endpoint. Once created, the token field must be used in the HTTP Authorization header using the Bearer scheme. An example of an HTTP request with a bearer token:

More information on the Bearer scheme can be found in RFC-6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage.

Security Scheme Type: HTTP
HTTP Authorization Scheme: bearerBearer format: JWT

IP Restrictions

It is possible to add IP restrictions to API keys and Bearer tokens. Doing so will reduce the risk of a compromised key. Keys and tokens with IP restrictions will not be usable outside the specified ranges and will yield a generic 401 Authentication Required error. IP restrictions can be expressed using the CIDR format (n.n.n.n/n).

CIDR block	Description
`185.184.111.39/32`	Single IP address
`102.177.115.120/29`	All IP addresses between `102.177.115.120` and `102.177.115.126` (inclusive)
`0.0.0.0/0`	The entire internet

More information on the CIDR format can be found in RFC 4632 - Classless Inter-domain Routing (CIDR).

Permissions

API keys and Bearer tokens can have one or more permissions assigned. These permissions allow you to restrict what actions can be performed with the credentials. Using multiple API keys and restricting their permissions to only what they need specifically (least privilege) is good practice.

For instance, if you access the Silverflow API from your data lake, you could create an API key just for that subsystem and restrict the permissions to charges:List and reports:All.

When you make an API call with an API key that does not have the appropriate permissions, you will get a 403 Forbidden error. The details of the message will explain which permission you need to make the call successfully. The following permissions are available:

Permission name	Permissions
`agents:Get`	Allows to retrieve an agent.
`agents:Update`	Allows to update an agent. Name, registered address, etc.
`agents:GetBin`	Allows to get a specific BIN of an agent.
`agents:ListBins`	Allows to list the BINs assigned to an agent.
`agents:CreateBearerToken`	It allows the creation of a temporary JWT token that can be used for disputes.
`agents:Activate`	Allows agent activation action.
`agents:All`	Allows all actions associated with the agent.
`apiKeys:Create`	Allows creating an API key with custom permissions.
`apiKeys:Get`	Allows to get specific API key.
`apiKeys:List`	Allows to list API keys for an agent.
`apiKeys:Update`	Allows to update API key.
`apiKeys:Archive`	Allows to delete API key.
`apiKeys:All`	Allows you to take any actions with API keys.
`eventSubscriptions:List`	It allows an agent to get a list of all event subscriptions.
`eventSubscriptions:Create`	Allows to create an event subscription.
`eventSubscriptions:Get`	Allows you to get a specific event subscription.
`eventSubscriptions:Update`	Allows to update an event subscription.
`eventSubscriptions:Archive`	Allows to remove an event subscription.
`merchants:Create`	Allows to create a new merchant.
`merchants:Get`	Allows to get specific merchants.
`merchants:List`	Allows to get all merchants for an agent.
`merchants:Update`	Allows to update merchant info.
`merchants:Archive`	Allows to remove a merchant.
`merchants:CreateAcceptor`	Allows to create a merchant acceptor.
`merchants:ListAcceptors`	Allows to get a list of all acceptors for a merchant.
`merchants:All`	Allows to do any actions with the merchant.
`acceptors:Get`	Allows to get a merchant acceptor.
`acceptors:Update`	Allows to update a merchant acceptor.
`acceptors:Activate`	Allows to activate a merchant acceptor.
`acceptors:Archive`	Allows to remove a merchant acceptor.
`acceptors:All`	Allows all actions with acceptors of a merchant.
`charges:Create`	Allows to create a charge.
`charges:Get`	Allows to get a charge.
`charges:Clear`	Allows to clear charge manually.
`charges:CreatePayout`	Allows to create a gaming payout charge.
`charges:CreatePos`	Allows to create a POS charge.
`charges:List`	Allows to get a list of all charges.
`charges:Reverse`	Allows to reverse a charge.
`charges:Refund`	Allows to refund a charge.
`charges:CancelOrRefund`	Allows to request a cancellation or a refund for a charge.
`charges:All`	Allows all actions with charges.
`disputes:List`	It allows an agent to get a list of all disputes.
`disputes:Get`	Allows an agent to get a specific dispute.
`disputes:All`	Allows all actions with disputes.
`disputes:ListDocuments`	Allows to list all dispute documents.
`disputes:AddDocument`	Allows to add a new document to a dispute.
`disputes:Accept`	Allows to accept liability of a dispute.
`disputes:Defend`	Allows to defend a dispute.
`disputes:ListHistory`	Allows to list event-history of a dispute.
`cardInfo:GetInfo`	Allows to get card info.
`reports:SettlementDetails`	Allows to get settlement details report.
`reports:DailySettlementTotals`	Allows to get daily settlement totals report.
`reports:QuarterlyNetwork`	Allows you to get quarterly reports for the card network.
`reports:NetworkFundsTransfers`	Allows retrieval of Network Funds Transfers
`reports:All`	Allows to get any reports.
`documents:All`	Allows all actions with documents.
`documents:Get`	Allows to get metadata of a document.
`documents:Archive`	Allows to delete a document.
`documents:Download`	Allows to download a document.
`documents:Upload`	Allows to upload a document.
`tokens:Create`	Allows to create a token.
`tokens:Get`	Allows to get a token.
`tokens:GetTokenData`	Allows to get the token data.
`tokens:CreateTokenCryptogram`	Allows to create a token cryptogram.
`tokens:Archive`	Allows to archive a token.
`tokens:All`	Allows all actions with tokens.
`processorTokens: Create`	Allows to create a processor token
`processorTokens: List`	Allows to get a list of processor tokens
`processorTokens: Get`	Allows to get a processor token
`processorTokens: Archive`	Allows to archive a processor token
`processorTokens: All`	Allows all actions with processor tokens

| all:All | Assigns all permissions. Use at your own risk. |