INTEGRATION

Getting Started
Authentication

INTEGRATION

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: bearer
Bearer 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. |