Signature

For live clients absolutely all requests should be signed. For the clients with other statuses, it is optional:

  • If the signature header isn’t sent, the request will be performed without any signature validations;
  • If the signature header is sent, the request signature will be verified.

In order for your request to be considered signed, the following header is required:

  • Expires-at - request expiration time as a UNIX timestamp in UTC timezone. We suggest to use +1 minute from the current time. The maximum value is 1 hour from now in UTC, otherwise ExpiresAtInvalid error will be raised.

Example: Expires-at: 1413466421

Authentication

All of the resources queried through the API are protected by 4 different headers, on different levels of security, as shown on the diagramm below:

Client ID and App secret

For your apps, all outgoing requests should be signed with Client-id and App-secret headers. These headers should be present in all of the requests passed through the API.

An example of a request listing all the countries the API supports can be found below:

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "App-secret: APP_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v3/countries

Client ID, App secret and Customer secret

In order to create tokens, logins and oauth providers, your app should pass the Customer-secret header inside the request, so the API can identify which customer the entity belongs to.

Example of Customer-secret request in the API:

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "App-secret: APP_SECRET" \
        -H "Customer-secret: CUSTOMER_SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"country_code\": \"XF\", \
                \"provider_code\": \"fakebank_simple_xf\", \
                \"fetch_type\": \"recent\", \
                \"credentials\": { \
                  \"login\": \"username\", \
                  \"password\": \"secret\" \
                } \
              } \
            }" \
        https://www.saltedge.com/api/v3/login

Client ID, App secret, Login secret and Customer secret

Since an app should be able to query information only about the logins it created, requests that query or modify logins should be signed with a Login-secret header.

Here is an example of a request which queries the information about a login, based on it’s secret.

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "App-secret: APP_SECRET" \
        -H "Customer-secret: CUSTOMER_SECRET" \
        -H "Login-secret: LOGIN_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v3/login