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. See here for a complete list of the available permissions.