Technical setup

Introduction

This guide describes how to set up your solution to integrate the Solaris APIs and communicate with Solaris' backend.

This guide is intended for a technical audience. In order to ensure a smooth onboarding experience, individuals integrating Solaris into their solutions should be familiar with the basics of REST APIs as well as OAuth2.

1. Environments

Solaris offers two environments to partners:

• Production: The "live" environment where Solaris partners offer services to their customers.

• Sandbox: A test environment that enables partners to verify their Solaris integrations before pushing changes that affect their customers.

  • Note: Please contact your Partner Manager before testing on Sandbox.

Base URLs for each environment:

• Production:

  • Authentication: https://auth.solarisbank.de
  • API: https://api.solarisbank.de

• Sandbox:

  • Authentication: https://auth.solaris-sandbox.de
  • API: https://api.solaris-sandbox.de

2. Authentication

For each environment, Solaris will provide you with a set of access credentials in the form of a client_id and client_secret.

You must provide these credentials to the Solaris OAuth2 API to retrieve your access token.

• Pass the credentials as a colon-separated string (i.e., client_id:client_secret) encoded using Base64 in the Authorization header of your request.

• Include the following URL-encoded parameters:

  • grant_type=client_credentials
  • scope=partners

Request URL:

POST https://auth.solarisbank.de/oauth2/token

Request example:

POST https://auth.solarisbank.de/oauth2/token
Authorization: Basic YXV0aC1jcmVkOjZyczZuZDYzbjg0dGMwZzBrcTV6aDUyYjV3emJwM2phcDRwc2t4d2pka2RmZ3c5YW9uM3g4Y3gyNGNqYzJtOXp6N3N6Z23=
Host: auth.solarisbank.de   # Sandbox URL: auth.solaris-sandbox.de
Content-Type: application/x-www-form-urlencoded
data-urlencode 'grant_type=client_credentials' 
data-urlencode 'scope=partners'

The API will return your access token in the access_token property of the response, along with some important metadata.

Click here to read the full API documentation.

Access token

You must include your access token in the header of every API request using the following format:

Authorization: Bearer {YOUR-TOKEN-HERE}

Access tokens expire over time. When a token expires and your solution uses it to call the Solaris API, you will receive the HTTP 401 Unauthorized response. In this case, your solution should call the OAuth2 API to generate a new token and then retry the request.

Permissions

Your access token provides you access to all Solaris API actions to which you have been granted permissions. Each API action is described using a policy. Solaris grants partners access to these policies based on their specific use cases and the Solaris products that they implement.

More info

See the Authentication guide for a full description of how authentication works on the Solaris platform.

3. Webhooks

The Solaris API allows you to create webhooks that send real-time notifications to your solution when certain events occur in Solaris' system, such as:

• A person was changed or deleted.
• An identification session has been completed.
• An account was closed.

Solaris recommends creating webhooks for all event types that are relevant to your solution. You can find a list of these in your solution document. For a complete list of Solaris event types, see the webhooks guide.

Create a webhook

To create a webhook, call the Solaris Webhooks API:

Request URL:

POST /v1/webhooks

In the request body, provide the following:

• The event_type to subscribe to.
• The url where the webhook notification should be sent.

Click here to read the full API reference.

Notification delivery

When an event of the specified event_type occurs, Solaris will automatically send a notification to the URL you provided to the API that contains a JSON payload.

Please implement the following response codes in your solution to inform Solaris about whether or not the notification was successful:

Any other response code places the message into a retry loop. For each failed delivery, Solaris' platform increases the attempt counter in the message header and the time span between retries.

Please note that after 20 unsuccessful retries, which will be sent over a period of 7 days, the message will automatically expire.

Notification content

A webhook notification contains two types of information:

• Metadata about the webhook, stored in the HTTP header. These properties are consistent for every event_type.
• The JSON payload of the webhook notification, which contains content specific to the event_type.

Verify notification contents

Solaris provides a signature hash in the Solaris-Webhook-Signature header of each notification that it sends. This allows you to verify that the webhook was in fact sent by Solaris (in case the webhook URL is open to the public).

To verify the signature, generate an HMAC digest from the webhook secret (returned when you created the webhook) and the content (JSON payload) of the notification and match it against the Solaris-Webhook-Signature string.

Here is an example of how to do this in Ruby:

digest_algorithm, signature = request.env['HTTP_SOLARIS_WEBHOOK_SIGNATURE'].split('=')
content = request.body.read

if OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new(digest_algorithm), secret, content) != signature
  halt(422, 'Signature not correct')
end

# process notification

4. Device monitoring

Solaris has introduced device monitoring as an additional layer of fraud prevention. Partners are required to collect device fingerprints from their (potential) customers' devices using the Seon SDK and then submit them to Solaris when calling certain API endpoints. Solaris will analyze the provided fingerprints when performing Customer Due Diligence checks and notify you of any suspected fraud using the PERSON_CHANGED webhook.

See the device monitoring guide for instructions on how to implement this requirement.