Authentication

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

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:

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:

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 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

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).

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

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.