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 also update and delete them, allowing for credential rotation.

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

Important: The secret is only returned once in the 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 authorise '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 that have IP restrictions will not be usable outside of 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 restrict what actions can be performed with the credentials. It is good practice to use multiple API keys and restrict their permissions to only what they need specifically (least privilege).

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`	Allows to create a temporary JWT token that can be used for disputes.
`agents:Activate`	Allows agent activation action.
`agents:All`	Allows all actions associated with 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 to do any actions with API keys.
`eventSubscriptions:List`	Allows to get s list of all event subscriptions for an agent.
`eventSubscriptions:Create`	Allows to create an event subscription.
`eventSubscriptions:Get`	Allows 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 merchant.
`merchants:List`	Allows to get all merchant 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 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`	Allows to get a list of all disputes for an agent.
`disputes:Get`	Allows to get a specific dispute for an agent.
`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 a card info.
`reports:SettlementDetails`	Allows to get settlement details report.
`reports:DailySettlementTotals`	Allows to get daily settlement totals report.
`reports:QuarterlyNetwork`	Allows to get quarterly report for card scheme.
`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.

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