Authentication

This is the currently supported stable version of the Silverfin API - version 4.

If you need information about migrating from the deprecated version 3 to version 4, please read: https://engineering.silverfin.com/silverfin-api-v4.

Authorization flow implements OAuth2 so you need a client_id and client_secret
to connect. This can be requested by a mail to [email protected]

API Mailing list

You can subscribe to our mailing list if you want to be kept up-to-date regarding any change we push on our API.

API changes

• Non-breaking changes, such as adding data to a payload or implementing a new endpoint, can happen at any time without any advance warning.
• Breaking changes, such as removal of data from a payload or removal of an endpoint, will be communicated in advance, with the length of deprecation notice proportional to scope & impact of the change.

OAuth endpoints

Authorization

When you redirect to the authorize url, you can pass the requested
scopes in the url with the scope parameter. The scopes should be
separated with spaces.

You have two options when requesting authorization:

• url without firm_id: {''}://{'<APPLICATION_ADDRESS>'}/oauth/authorize

• url with firm_id: {''}://{'<APPLICATION_ADDRESS>'}/f/:firm_id/oauth/authorize

Note that in either case the user will have the option to authorize access to any of the firms they belong to.
If /f/:firm_id is included in the URL, the selector presented to the user will pre-select this firm,
but you should not assume that access will be granted to the firm you requested.

In addition to the authorization code, the response will contain an additional url parameter authorized_firm_id,
denoting the firm to which your application has been granted access. Please be sure to make note of it
as you will need it for all subsequent requests.

Access token request

• url must include firm_id: {''}://{'<APPLICATION_ADDRESS>'}/f/:firm_id/oauth/token

OAuth flow

We use standard OAuth. The typical flow goes like this:

1. Perform a GET request to /oauth/authorize with url parameters client_id, redirect_uri,
   scope (a space separated list of requested scopes) and response_type=code
2. Once the user grants your app permission to access their data, the browser will redirect to
   redirect_uri with a url parameter code
3. With this code, your application will have 10 minutes to perform a POST request to /oauth/token with parameters
   client_id, client_secret, code, redirect_uri and grant_type=authorization_code

After following these steps, you will have an access token and a refresh token. The access token
is valid for 2 hours, while the refresh token currently does not expire.

NOTICE: As of August 9, 2022, refresh tokens will remain valid for 60 days. Please read
our announcement for more details.

With the refresh token, you can request a new access token / refresh token pair:

4. Perform a POST request to /oauth/token with parameters: client_id, client_secret,
   refresh_token, redirect_uri and grant_type=refresh_token.

Each refresh token can be used only once. As soon as the new access token is used to access the API
for the first time, the previous refresh token will be revoked.

Scopes

We currently support the following scopes: administration:read, administration:write,
communication:read, communication:write, financials:read, financials:write,
financials:transactions:read, financials:transactions:write, links,
permanent_documents:read, permanent_documents:write,
user:email, user:firm, user:profile, webhooks, workflows:read, workflows:write

The scopes are also coupled to the application and added to the
application based on your needs.

Error codes

When an error occurs, we return a response with a specific status code and a JSON payload with the following format:

{
  error: "A message describing the issue."
}

Please referer to the following table when you receive such an error:

API formats

The Silverfin API supports application/pdf, application/json and application/vnd.openxmlformats-officedocument.spreadsheetml.sheet media types as Content-Type values.

If the body is present in a request, with a Content-Type header value that is of an unsupported type a "415 Unsupported Media Type" error code will be returned by the Silverfin API.

In case the Content-Type header is missing or malformed the API will return a 403 Forbidden response.

Internationalization

Endpoint outputs and generated documents can be translated by passing the Accept-Language header, such as:

curl -X GET --header 'Accept: application/json' --header 'Accept-Language: nl' --header 'Authorization: ...' 'http://localhost:3000/api/v4/f/...'