Integration & setup

• Intro
• Integration methods
• Typescript Web SDK
• Prebid
• Request API: Headsup endpoint
• Request API: Stack endpoint
• Request API: JSON endpoint
• Request API: AD endpoint
• JSON endpoint: full response structure
• Adserver Features
• Automated image resizing
• Video Content Cache
• IP override for server-side connections
• CPM Priority Sorting
• Reference
• Reserved Target Prefixes
• Supported Currencies
• OIDC Federation Setup Guide (SSO)

Intro

Adhese Gateway and Direct Ad Server

The Gateway and Ad Server operate entirely server-side, ensuring that client implementations remain as straightforward as possible and preventing the exposure of business rules and configuration. This allows for straightforward integration across a wide range of platforms and devices, eliminating the need for complex development processes.

Once implemented, no further client-side changes are required. Publishers can use a centralised web application to enable new demand sources, add or modify the data they share with their partners, and set business rules, multipliers and exceptions. These changes are executed instantly, without any need for intervention from web administrators or application developers.

The implementation for using Gateway or Direct Ad Server technologies is the same. Below are the links to the various repositories with examples and code.

Libraries & SDKs

Adhese has a TypeScript-based SDK for web integrations. More information can be found here: https://documentation.adhese.org/books/integration-setup/page/typescript-web-sdk

Prebid Compatible

Gateway can be used as a bidder for both Prebid.js and Prebid Server, and has been incorporated into various custom wrappers created by publishers and SSPs.

More information can be found here: https://documentation.adhese.org/books/integration-setup/page/prebid

API implementation

Any publisher can implement their Adhese instance as a pure API, calling the ad server endpoints directly from their mobile app, CMS system or connected TV app. They receive campaigns for multiple placements in one request, which can be visualised according to device and context.

Documentation on the different Request API endpoints can be found here: https://documentation.adhese.org/books/integration-setup/chapter/ad-delivery-integration-methods

Migrating your old ad server to Adhese

Depending on the customer's requirements, migration from an existing ad server to Adhese can be achieved in several ways.

One approach is to focus on getting the Adhese tags up and running. Based on the inventory setup, all tags are made available. Existing tags from the legacy ad server can be implemented in Adhese as standard campaigns that serve the legacy tags as third-party ads. To ensure continuity, 100% of the inventory is sent to these campaigns. New campaigns booked in Adhese can take priority over the legacy tags if required. Eventually, the legacy campaigns will stop running, as no further traffic is needed. Any new or updated campaigns will be booked directly in Adhese.

Another approach is to postpone tagging and start booking new campaigns in Adhese. Adhese tags or third-party tags can then be uploaded to the legacy ad server. This can be done on a per-campaign basis or you can send 100% of the traffic to Adhese campaigns in the legacy system. As the tags are distributed across the client's network, the same Adhese creatives will be displayed, either by being called directly through the Adhese tags or by being passed through the tags of the legacy ad server.

Integration methods

Typescript Web SDK

The Adhese TypeScript SDK simplifies ad integration across web environments by handling the underlying request and response logic, allowing you to implement ad placements without dealing with low-level API calls.

At the same time, the SDK remains flexible: it allows you to plug in custom logic where needed, giving you full control for more advanced or tailored integrations.

The getting started guide walks you through:

• Installing the SDK
• Initialising a client
• Making ad requests
• Rendering ad responses

The full documentation can be found on https://adhese.github.io/sdk_typescript/

Integration options

The SDK supports multiple integration approaches, depending on your environment:

NPM 

Install the SDK via NPM and integrate it into modern JavaScript or TypeScript projects.

React

Use the SDK within React applications to manage ad slots and lifecycle in a component-based way.

Standalone JS script

Include the SDK as a standalone script for simple integrations without a build step. Ideal for quick setups or environments where bundling is not available.

The standalone script could be hosted and maintained by the Adhese team. Contact support if you wish to discuss this option in more detail. 

Key Features

Slot Management

Slots are the fundamental units for ad placement. The SDK supports three slot registration methods:

• Automatic DOM detection - scan for elements with adunit class
• Pre-initialization slots - declare slots before page load for early ad fetching
• Manual registration - dynamically add slots via API

Additional slot capabilities include:

• Device-specific format selection (responsive ads via media queries)
• Lazy loading with viewport detection
• Dual render modes (iframe or inline)
• Custom setup hooks for advanced control

Configuration & Parameters

At initialization, you can set:

• Account ID (required)
  
• Targeting parameters (2-character prefixes matching your adserver configuration)
• URL and referrer logging preferences
• Lazy loading settings
• Device type detection rules (customizable media queries)

Event System

Subscribe to lifecycle events:

• Slot lifecycle (add, remove, dispose)
• Request/response events
• Consent & parameter changes
• Debug mode toggles
• Impressions & viewable tracking

Consent Management

Supports regulatory compliance via:

• Binary consent (yes/no)
• TCF API v2 integration
  

React Integration

Dedicated React SDK provides:

• AdheseProvider context wrapper
• useAdhese hook for instance access
• useAdheseSlot hook for slot creation
• AdheseSlot component with JSX rendering support
• Placeholder support during ad loading

SDK Repository

The SDK is actively maintained on GitHub and publicly available: https://github.com/adhese/sdk_typescript

Prebid

Prebid is a free and fully open source header bidding solution available to any publisher, dedicated to header bidding in the ad tech industry.

Header bidding allows publishers to create a short delay in ad serving to obtain bids from multiple demand partners before deciding on which ad to display, enabling competitive pricing and higher revenue.

More information on Prebid | Prebid.js Bidder | Prebid Server Bidder

How do Adhese and prebid work together

When a publisher implements Adhese through Prebid, they're participating in a header bidding auction where multiple demand partners (including Adhese) compete to deliver ads. Here's how the process works:

Auction Initiation

When a page loads, Prebid sends simultaneous bid requests to multiple bidders - including Adhese - rather than sequential requests. This concurrent approach is one of Prebid's key features for managing latency. All bidders (including Adhese) receive their request at roughly the same time.

Adhese's Role in the Auction

Adhese acts as a bidder/SSP within Prebid's ecosystem. Through the Prebid adapter, Adhese receives ad requests and returns competitive bids and creatives. The adapter translates Prebid's standardized request format into Adhese's API requirements and vice versa.

Bid Submission & Timeout Management

Publishers set a timeout value (typically 1-3 seconds) that determines how long Prebid waits for responses. Adhese must return its bid within this window. If Adhese doesn't respond in time, Prebid excludes it from that auction round. This timeout mechanism prevents slow bidders from degrading page performance.

Ad Selection

After all bidders respond, Prebid passes the winning bid to the publisher's ad server. If Adhese wins, its creative is selected and delivered, leading to an impression in Adhese.

Targeting & Parameters

Both Prebid and Adhese support custom targeting. Publishers can pass first-party data (like content categories, user segments, or location) through both systems, giving Adhese context for more accurate bidding.

Impression Tracking

After an ad is selected and rendered, Adhese can track impressions and viewability through Prebid's event system, feeding performance data back to their platform.

Bid Configuration Params

Request API: Headsup endpoint

The headsup endpoint returns all the materials for the campaigns running on the requested DOOH position.
It can be used by the DOOH screens to retrieve and cache all materials at the beginning of the day to avoid delays by having to download materials during the day. 

To ensure that the assets are included in the response, the Use in heads-up file setting must be enabled at format level. This action can be performed by all admin users in the Adhese UI.

https://headsup-[customer].adhese.org/api/headsup/download-list/sl[positioncode]

Response

 The JSON response consists of a "media" array that may be empty or populated with multiple ad objects, depending on the number of active campaigns. The structure of an ad object is fixed and can not be customized. 

The ID and URL from which to download the file is identical and is also available in the stack endpoint that will be used to download DOOH playlists during the day.

Example

{
    "media":[
        {
            "ad":{
                "id":"https://pool-demo.adhese.com/pool/lib/562_2nd_1.mp4",
                "mime":"video/mp4",
                "curl":"https://pool-demo.adhese.com/pool/lib/562_2nd_1.mp4",
                "filesize": 15470592,
                "checksum":"071f717962db99cc137d138696d33209f2e4818d42a54f70dfa6606eeb1b640b"
            }
        },
        {
            "ad":{
                "id":"https://pool-demo.adhese.com/pool/lib/560_2nd_1.mp4",
                "mime":"video/mp4",
                "curl":"https://pool-demo.adhese.com/pool/lib/560_2nd_1.mp4",
                "filesize": 15470592,
                "checksum":"4e78745a33518ff22c1c9f39852a49c1c0fadd0adf722e3394ad1215d5e5ff5b"
            }
        },
        {
            "ad":{
                "id":"https://pool-demo.adhese.com/pool/lib/561_2nd_1.mp4",
                "mime":"video/mp4",
                "curl":"https://pool-demo.adhese.com/pool/lib/561_2nd_1.mp4",
                "filesize": 6582272,
                "checksum":"64d2eab6d51b208c0cec3fc4d64c53381e5d41ae2a1d4c5b7704b1818bdb6158"
            }
        }
    ]
}

Request API: Stack endpoint

The stack endpoint allows you to request one position for which Adhese will return a list of ads. There are 2 versions: 

1. /m/stack/: returns a limited amount of ads
2. /e/stack/: returns an unlimited¹ amount of ads²

1 The adserver rules still apply and will influence which campaigns are part of the response. Not all booked campaigns are necessarily part of the returned array. 

2 The /e/stack/ endpoint must be enabled by Adhese support before it becomes available

m/stack request

https://ads-[customer].adhese.com/m/stack/sl[positioncode]/[target prefix][target value]?max_ads=[amount]

1 A configuration on the adserver can be activated to ensure the max_ads value never exceeds a specific limit. When the parameter is left empty, the configured limit will be used instead. 

e/stack request

https://ads-[customer].adhese.com/e/stack/sl[positioncode]/[target prefix][target value]

Stack response

The response contains JSON code: an ads array that will either be empty or populated with one or more objects, depending on the number of active campaigns. 

The structure of the objects within the array is determined by the advar template used when setting up the creatives. 

{
    "ads":[
        {
            "id":"https://pool-demo.adhese.com/pool/lib/562_2nd_1.mp4",
            "dur":28.07,
            "prio":15,
            "booking_prio":0,
            "publisher":"1",
            "key":"",
            "proofOfPlay":"https://ads-demo.adhese.com/track/3474/sl357/tlnone/piplayer_id/A2?1746011926824",
            "error":"https://ads-demo.adhese.com/track/3474-PLAY_ERROR_[ERRORCODE]/sl357/tlnone/piplayer_id/A2/?1746011926824"
        },
        {
            "id":"https://pool-demo.adhese.com/pool/lib/561_2nd_1.mp4",
            "dur":11.45,
            "prio":15,
            "booking_prio":0,
            "publisher":"1",
            "key":"",
            "proofOfPlay":"https://ads-demo.adhese.com/track/3444/sl357/tlnone/piplayer_id/A2?1746011926824",
            "error":"https://ads-demo.adhese.com/track/3444-PLAY_ERROR_[ERRORCODE]/sl357/tlnone/piplayer_id/A2/?1746011926824"
        },
        {
            "id":"https://pool-demo.adhese.com/pool/lib/560_2nd_1.mp4",
            "dur":18.85,
            "prio":15,
            "booking_prio":0,
            "publisher":"1",
            "key":"",
            "proofOfPlay":"https://ads-demo.adhese.com/track/3455/sl357/tlnone/piplayer_id/A2?1746011926824",
            "error":"https://ads-demo.adhese.com/track/3455-PLAY_ERROR_[ERRORCODE]/sl357/tlnone/piplayer_id/A2/?1746011926824"
        }
    ]
}

Common response Fields

Sorting the returned list

The order in which the ads array is populated can be be configured by using the sequence property in the advar template.
As value you can use a number that is filled in through the advar form, or use one of the Adhese macro's that return an ID.

When the sequence property is added and given a value, the adserver will sort the available ads based on its value. In the example below we use the CREATIVE ID to sort the array from lowest ID to highest ID. 

"sequence": <ADHESE_LIB_ID>

The sequence property is only used by the adserver and will be removed before the response is returned

Request API: JSON endpoint

The JSON endpoint is the foundation of every display integration with Adhese. It gives you direct access to the ad server and Gateway without an SDK or library: you build the request, and Adhese returns the ads as JSON. Any environment that can send an HTTPS request and parse JSON can use it. A backend service, a CMS, a mobile app, ...

The Typescript Web SDK and the Prebid adapter use this same endpoint under the hood. If you use one of those, you do not need this page for implementation, but it remains the reference for what actually happens under the hood.

The API is public and requires no authentication and cookies are not required for an integration to work.

POST request

Host

Each Adhese account has its own endpoint. The default pattern is:

https://ads-[account].adhese.com/json/

Request body

The POST body is a JSON object with up to three top-level properties:

{
    "slots": [
        {
            "slotname": "some_slot"
        },
        ...
    ],
    "parameters": {
        "kw": [
        "cheese",
        "wine"
        ],
        ...
    },
    "user": {
      "ext": {
        "eids": []
      }
    }
}

slots

An array of slot objects — one per ad placement needed for the current page or application state. At least one slot is required.

Each slot object contains at minimum a slotname: the unique identifier of the placement as configured in your Adhese account. Campaigns are targeted against these names.

"slots": [
    { "slotname": "some_slot" },
    { "slotname": "another_slot" }
]

Each slotname may appear only once per request. Duplicates cause the request to be rejected with status 442.

parameters

An object of targeting attributes describing the page, user, or context. Keys are fixed two-character codes defined in your Adhese account; values are always arrays of strings.

All parameters are optional — omit a key entirely, or send an empty array, when there is nothing to pass.

"parameters": {
    "kw": ["cheese", "wine"],
    "mi": ["ABCDEF123456"]
}

In this example, kw carries search keywords and mi a member ID. Reserved parameter codes are listed on Request target parameters. 

Slot-level parameters

A slot object can carry its own parameters property with the same structure. For each slot, request-level and slot-level parameters are merged. Use this for attributes that differ per placement, such as position on the page:

"slots": [
    {
        "slotname": "some_slot",
        "parameters": { "ps": ["top"] }
    },
    {
        "slotname": "another_slot",
        "parameters": { "ps": ["bottom"] }
    }
]

user

Reserved for passing identifiers from external ID providers to buyers further down the chain, mainly in an open-market context:

"user": {
    "ext": {
        "eids": []
    }
}

If you think you need this, contact Adhese Support before implementing.

Complete request example

{
    "slots": [
        { "slotname": "homepage_banner" },
        { "slotname": "homepage_rectangle_top" },
        { "slotname": "homepage_rectangle_bottom" },
        {
            "slotname": "homepage_halfpage",
            "parameters": { "ps": ["right"] }
        }
    ],
    "parameters": {
        "id": ["1234567890ABCD"],
        "ct": ["computers", "laptops"],
        "kw": ["cheese", "wine"]
    }
}

Here id is a user ID, ct product categories, and kw search keywords.

GET request

The GET version of the ad request contains the same information as the POST version with one limitation:
slot level parameters are not supported.

Example request

https://ads-[account].adhese.com/json/sl_sdk_example_-leaderboard/ctsports;soccer?t=1784033344461

Response codes

When handling errors programmatically, read the x-adhese-bad-request response header for the specific message.

Response object

A successful response contains a JSON array with one object per delivered ad. The objects contain many attributes; the complete field reference lives at General JSON response structure.

The most important attributes required for custom integrations are:

Trimmed response example

[
    {
        "slotName": "homepage_banner",
        "adFormat": "714x224",
        "width": "714",
        "height": "224",
        "tag": "<div>…ad markup…</div>",
        "trackedImpressionCounter": "https://ads-[account].adhese.com/track/…",
        "viewableImpressionCounter": "https://ads-[account].adhese.com/track/…-Adhese_IABview/…",
        "clickTag": "https://ads-[account].adhese.com/raylene/…/UR",
        "orderName": "Example Campaign",
        "creativeName": "Example Creative",
        "extension": {
            "mediaType": "banner",
            "prebid": {
                "cpm": { "amount": "13.047", "currency": "EUR" }
            }
        }
    }
]

Rendering and tracking workflow

For each ad in the response, a correct display integration does the following, in order:

1. Match the ad to its container using slotName.
2. Render the tag markup inside a container sized by width × height.
3. Call trackedImpressionCounter the moment the ad is added to the page.
4. Observe viewability (e.g. with an Intersection Observer) and call viewableImpressionCounter once the ad has been ≥50% in view for ≥1 second.
5. Wrap the creative's landing-page link in the clickTag URL so clicks are counted and redirected.

Skipping step 3 or 4 - or executing them at the wrong time - is the most common cause of reporting discrepancies between Adhese and third-party measurement.

Event tracking

Beyond impressions and clicks, you can register custom events (e.g. video quartiles, expansions, interactions) by constructing tracking URLs from the response data.

Building a custom event tracking URL

https://[ad domain]/track-[event label]/[response.id]/sl[response.slotID]/II[impressionID]

• event label : a name of your choosing for the event; it will appear in reporting
• response.id, response.slotID : taken from the ad's response object
• impressionID: this ID is not provided through a specific object in the response, but can be found in the provided tracking URL's such as the trackedImpressionCounter. This value is prefixed by the code II

The easiest way to build a custom tracking URL is to take the viewableImpressionCounter URL and replacing the Adhese-IABview label with a custom one. 

Request API: AD endpoint

The AD endpoint is used for integrations that can't parse a JSON response and require the response in a specific markup instead. It is typically used for video and audio setups, where ads are requested by media players and follow the VAST protocol in XML.

The API is public and requires no authentication and cookies are not required for an integration to work.

Request method

The AD endpoint supports GET requests only. As with the GET version of the JSON endpoint, slot-level parameters are not supported.

Unlike the JSON endpoint, only one placement can be retrieved with each call

URL structure

A request URL is built from the sections below, in order. Sections marked repeatable can appear more than once.

Example request

https://ads-demo.adhese.com/ad/sldemo.com_kitchen-billboard/dtdesktop

Broken down:

Response

A successful request returns the ads in the requested markup (VAST XML for video/audio setups).
This markup is determined by the advar template used to create the banner that is returned by the request. 

If no ads are available, the response contains no ads. This is still a successful 200 response, not an error.

Response codes

Error handling

When handling errors programmatically, read the x-adhese-bad-request response header for the specific error message.

JSON endpoint: full response structure

The following code block is an extracted example of a JSON object. A list of all available JSON fields and their descriptions can be found below the code block.

{ 
	...
	"adFormat": "wideskyscraper", 
	"adspaceId": "61721",
	...
    "adspaceStart": "1433714400000",
	"adspaceEnd": "1483225199000",
	"adType": "SKY",
	...
	"creativeName": "Example Billboard News",
	...
    "deliveryMultiples": "free",
	...
 	"ext": "swf",
	...
    "height": "600",
    "id": "295057",
    "libId": "96393",
	"orderId": "16643",
    "orderName": "Example - BillBoard Campaign",
	...
    "priority": "1", 
	...
    "slotName": "_test-site_homepage_-SKY", 
    "swfSrc": "http://1.adhesecdn.be/pool/lib/96393.swf",
    "tag": "<object id='-1756524077' classid='clsid:D27CDB6E-AE6D-11cf-96B8-444553540000' codebase='http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=5,0,0,0' WIDTH=160 HEIGHT=600><param NAME=movie VALUE='http://1.adhesecdn.be/pool/lib/96393.swf?clickTAG=http://host4.adhese.be/295057/http%3A%2F%2Ftrack.adform.net%2FC%2F%3Fbn%3D3515419'/><!--[if !IE]>--><object type='application/x-shockwave-flash' data='http://1.adhesecdn.be/pool/lib/96393.swf?clickTAG=http://host4.adhese.be/295057/http%3A%2F%2Ftrack.adform.net%2FC%2F%3Fbn%3D3515419' width='160' height='600'><!--<![endif]--><param NAME='quality' VALUE='high'/><param NAME='allowScriptAccess' VALUE='always'/><param NAME='wmode' VALUE='transparent'/><a target='_blank' href='http://host4.adhese.be/295057/http://track.adform.net/C/?bn=3515419'><img src='http://1.adhesecdn.be/pool/lib/96394.jpg'></a><!--[if !IE]>--></object><!--<![endif]--></object>",
    ...
	"timeStamp": "1396357433000",
    "tracker": "http://ads.adhese.be/track/295057//sl242///////inadttr12842;adttrbiz;adttrfood;adttrhealth;adttrimmo;adttrlifestyle;adttrmultimedia;adttrsport;adttrtrav;adttrvoetbal;adttrwielrennen/brTelenet N.V./coBE/rgBE11///isTelenet N.V.//////////A2141.135.96.213.1395820307192918/O_/A_/C_", 
    "trackingUrl": "http://track.adform.net/adfserve/?bn=3515419;1x1inv=1;srctype=3;ord=",
    "url": "http://host4.adhese.be/295057/http://track.adform.net/C/?bn=3515419",
    "width": "160",
}

Adserver Features

Automated image resizing

What is Automated image resizing?

Adhese uses the AWS Lambda image-resizing service to automatically reduce the dimensions and file size of images uploaded as part of a creative. This allows you to request multiple versions of the image. 

The image resizing feature is a custom feature that requires setup and integration. Please contact Support if you would like to use it.

As the image resizer uses an external service, enabling this feature may incur additional costs depending on your licensing agreement with Adhese. Please contact us if you are unsure.

Why use image resizing?

Using resized images improves responsive design and reduces bandwidth usage. Setting a viewport threshold ensures that smaller images are served to smaller displays, thereby reducing file sizes and bandwidth consumption. This is particularly beneficial for mobile-based implementations.

How to use image resizing?

By adding an extra parameter .width.{px} to the image URL, you can request a resized version with a specific width. The height will scale automatically to maintain the aspect ratio.

The logic to add the extra 'width' value could be added to an Advar template in Adhese itself or to the code that processes the ad markup client-side.

For example:

https://demo-preview.adhese.org/pool/lib/8_2nd_1.png
https://demo-preview.adhese.org/pool/lib/8_2nd_1.png.width.150

Video Content Cache

Adhese has a content cache system that facilitates video ad delivery in two ways:

1. It allows prebid offers to be made on video ads by providing a URL containing the VAST markup of the ad that won the bid. Once a video ad is requested, it is retrieved via the provided link.
2. This allows for fast and seamless delivery, as subsequent requests for the same ad can be delivered from the cache. 

The content cache is a custom feature that requires setup. Please contact Support if you would like to make use of it.

Content Cache Setup

There are two main ways to make use of the content cache feature.

• Configure your Adhese Prebid server to use the feature by default.
• Explicitly request caching in a post request.

In both cases the value that must be added or enabled is:

"vastContentAsUrl": true

When caching is enabled, the VAST content will be available via a URL with a time-to-live of 3,5 hours, after which a new request must be made to the ad adserver.

IP override for server-side connections

What

By default, all ad requests to the Adhese ad server use the IP of the device that sends the request for all IP-related logic, such as geo-location targeting.
This behaviour makes it impossible to set up user-based location targeting in server-to-server setups, as the ad server would use the server's IP instead of the end user's IP.
To solve this, Adhese provides functionality that overrides the server's IP with the user's IP.

How

The user's IP can be added to the request via the X-Forwarded-For header. The ad server will pick up this header and override the default IP address from which the request is sent.

Please contact Support if you’d like to make use of this feature.

CPM Priority Sorting

Adhese determines share via priority. The end date of a booking also increases priority: the earlier the end date, the higher the priority and the larger the share. Two bookings with the same priority setting, but with different end dates will result in the booking with the earlier end date receiving a larger share.

The same share advantage for the booking end date applies when two bookings have different CPM values. Depending on your business case, this may be undesirable, as the booking with the earliest end date and the lowest CPM receives a greater share than a competing booking with a later end date and a higher CPM.

Adhese has an account configuration that can alter the Publish logic to prioritise bookings with a higher CPM instead of bookings with an earlier end date. In the event of two bookings with different end dates and CPM values, the booking with the higher CPM will receive a larger share.

This setting can be enabled for one priority level across the entire account. This means that the other priority levels will still be sorted by end date.

To enable CPM Priority Sorting, please contact Support.

Reference

Reserved Target Prefixes

All target codes which are part of the following list and all codes starting with x, y or z are reserved

Supported Currencies

Adhese supports multiple currencies for use in e.g. campaign budgets. The table below lists all currencies currently supported by Adhese.

OIDC Federation Setup Guide (SSO)

This document describes the requirements for setting up Single Sign-On (SSO) via OpenID Connect (OIDC) between your Identity Provider (IdP) and the Adhese platform.

1. Overview

We use OIDC-based identity federation to allow your users to log in to the Adhese platform using your organisation's Identity Provider (IdP). Our platform acts as the Service Provider (SP)/Relying Party (RP), while your IdP handles user authentication.

2. Information We Need From You

To configure the connection on our side, we need the following from your IdP:

If your IdP supports a discovery endpoint, most of the above can be derived automatically. In that case, providing the discovery URL, Client ID, and Client Secret is sufficient.

3. Information We Provide To You

You will need the following from us to configure your IdP:

4. Required Scopes and Claims

Required Scopes

Required Claims

Important: The email_verified claim is an optional claim per the OIDC specification, meaning IdPs are not required to include it by default. Please verify that your IdP is configured to include this claim in the ID token when the email scope is requested. Additionally, the value must be true — users whose email address has not been verified at the IdP level will not be able to log in.

Optional Scopes and Claims

The profile scope is not required but recommended. It enables us to display user-friendly names in the Adhese UI.

5. Role Mapping (Optional)

User roles can be managed directly within the Adhese platform. However, if you prefer to manage roles centrally from your IdP, we support automatic role assignment based on a custom claim in the ID token.

How It Works

• You choose the claim name (e.g., adhese_role) — let us know which name you use so we can configure the mapping on our side.
• The claim value can be a single role (string) or multiple roles (array).
• Roles are mapped automatically on each login, so changes in your IdP are reflected immediately.

Single role example:

{
  "adhese_role": "admin"
}

Multiple roles example:

{
  "adhese_role": ["viewer", "creative_approver"]
}

Available Roles — Classic UI

Available Roles — New UI

If you do not configure role mapping, roles will be managed manually within the Adhese platform by an administrator.

6. Setup Checklist

Your side (IdP)

• Register a new OIDC client/application for Adhese
• Configure the redirect URI provided by us as an allowed callback URL
• Ensure the openid and email scopes are enabled
• Verify that the email_verified claim is included in the ID token with a value of true
• (Optional) Enable the profile scope
• (Optional) Configure a custom claim for role mapping
• Share the Client ID, Client Secret, and discovery URL (or individual endpoints) with us

Our side (Adhese)

• Provide the redirect URI
• Configure the IdP connection with the provided endpoints and credentials
• Configure scope requests (openid, email, and optionally profile)
• Configure essential claim validation for email_verified
• (Optional) Configure role mapping based on the agreed custom claim
• Perform a test login together

7. Testing

Once both sides are configured, we recommend performing a joint test:

1. Initiate a login on the Adhese platform
2. Verify that the redirect to your IdP works correctly
3. Authenticate with a test user
4. Verify that the callback to Adhese succeeds
5. Confirm that the user's email and profile information are correctly displayed
6. (If applicable) Confirm that role mapping is applied correctly

If the login fails with an error related to the essential claim, the most common causes are:

• The email scope is not enabled on the IdP
• The email_verified claim is not included in the ID token
• The user's email is not verified at the IdP level (email_verified: false)