# Technical setup

## Introduction

Set up your solution to integrate the Solaris APIs. This guide covers environment configuration, authentication, webhook subscriptions, and device monitoring.

## Environments

Solaris offers two environments:

- **Production:** The live environment for customer services.
- **Sandbox:** A test environment for verifying integrations.
  - **Note:** Contact your Partner Manager before testing on Sandbox.


**Base URLs:**

- **Production:**
  - Authentication: `https://auth.solarisbank.de`
  - API: `https://api.solarisbank.de`
- **Sandbox:**
  - Authentication: `https://auth.solaris-sandbox.de`
  - API: `https://api.solaris-sandbox.de`


## Authentication

Use the `client_id` and `client_secret` provided by Solaris to retrieve your **access token**.

To request a token:

1. Encode your credentials as a Base64 colon-separated string (`client_id:client_secret`).
2. Pass this string in the **Authorization** header.
3. Include the following URL-encoded parameters:
  - `grant_type=client_credentials`
  - `scope=partners`


**Request URL**


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


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

grant_type=client_credentials&scope=partners
```

The API returns the token in the `access_token` property.

[Authentication API reference](/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.

## Webhooks

Subscribe to **webhook events** to receive real-time notifications when specific actions occur in the Solaris system, such as:

- A person is changed or deleted.
- An identification session completes.
- An account is closed.


Use these notifications to trigger automated processes in your solution or to send status updates to your customers.

**Compliance requirement:**
You **must** subscribe to the [mandatory webhook events](/api-reference/webhooks#mandatory-webhook-events) regardless of your product. Failing to process these events may result in compliance violations.

Check your specific product guides for additional required webhooks.

### Subscribe to an event

Call the Solaris Webhooks API to create a subscription:

**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) | Delivery successful. |
| `410` (Gone) | Delivery rejected. Solaris **cancels the subscription** for this URL. |
| `422` (Unprocessable Entity) | Delivery rejected. Solaris will not retry. |


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

## Device monitoring

Collect **device fingerprints** to prevent fraud. Use the [Seon SDK](https://seon.io/resources/device-fingerprinting/) to collect data from customer devices and submit it to Solaris when [calling relevant API endpoints](/guides/kyc/device-monitoring#actions-that-require-device-monitoring).

Solaris analyzes these fingerprints during [Customer Due Diligence](/guides/kyc/cdd) and notifies you of suspected fraud via the [PERSON_CHANGED webhook](/api-reference/onboarding/webhooks/webhook-events/paths/person_changed/post).

See the [device monitoring guide](/guides/kyc/device-monitoring) for implementation details.