Skip to content
/
1. Technical setup
Last updated

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

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

grant_type=client_credentials&scope=partners

The API returns the token in the access_token property.

Authentication API reference

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.

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

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.

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 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 CodeReaction
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) 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

Device monitoring

Collect device fingerprints to prevent fraud. Use the Seon SDK to collect data from customer devices and submit it to Solaris when calling relevant API endpoints.

Solaris analyzes these fingerprints during Customer Due Diligence and notifies you of suspected fraud via the PERSON_CHANGED webhook.

See the device monitoring guide for implementation details.

Previous page
Next page