# 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:**


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

**Request example:**


```shell
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.](/api-reference/authentication)

### Access token

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


```shell
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.

Warning
For security reasons, do not include your access token in the request URLs of any API calls.

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

To add or change permissions, please contact your Partner Manager.

### More info

See the [Authentication guide](/api-reference/authentication) 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.](/api-reference/webhooks)

### Create a webhook

To create a webhook, call the Solaris Webhooks API:

**Request URL:**


```shell
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.](/api-reference/onboarding/webhooks/#tag/Webhook-subscription/paths/~1v1~1webhooks/post)

The webhooks API returns a `secret` when you successfully create a webhook. Use this `secret` to validate the authenticity of the notifications you receive at the webhook URL. See the [next section](#verify-notification-contents) for more information.

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

| Response Code | Reaction |
|  --- | --- |
| `2xx` - Success | Solaris' platform assumes that the delivery was successful. |
| `410` - Gone | The delivery is marked as rejected, and Solaris' platform will **cancel the subscription** on this particular URL. |
| `422` - Unprocessable Entity | The delivery is marked as rejected, and Solaris' platform will not attempt to re-send the notification. |


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](#create-a-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:


```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](https://seon.io/resources/device-fingerprinting/) and then submit them to
Solaris when [calling certain API
endpoints](/guides/kyc/device-monitoring#actions-that-require-device-monitoring). Solaris will analyze the
provided fingerprints when performing [Customer Due Diligence](/guides/kyc/cdd)
checks and notify you of any suspected fraud using the [PERSON_CHANGED
webhook](/api-reference/onboarding/webhooks/#tag/Webhook-events/paths/person_changed/post).

See the [device monitoring guide](/guides/kyc/device-monitoring) for
instructions on how to implement this requirement.