Skip to main content

API Reference



Method that returns a token, which is required to instantiate a UnifiedConsentByOsanoClient. The issuer, configId, customerId, and the returned token are not sensitive. The token can be generated by, or passed along to the client application.

This token will give you access to all UnifiedConsentByOsanoClient methods EXCEPT the following (see createClient for more information on enabling these methods):

  • UnifiedConsentByOsanoClient.mergeAnonymousSubject
  • UnifiedConsentByOsanoClient.saveProfile
  • UnifiedConsentByOsanoClient.verifySubjectProfile
  • UnifiedConsentByOsanoClient.getProfileVerificationCode
  • UnifiedConsentByOsanoClient.mergeSubjects


import { UnifiedConsentByOsanoSDK } from '@unifiedconsentbyosano/cmp-javascript-sdk'

const accessToken = await UnifiedConsentByOsanoSDK.getToken(
/** URL of authorization services provider */
issuer: string,
/** The config Id */
configId: string,
/** The Client Id */
customerId: string


The UnifiedConsentByOsanoClient can be used from a browser or node environment. It requires the ClientConfig parameter with an access token to be able to instantiate it. Returns a UnifiedConsentByOsanoClient instance.

At a minimum the token and apiUrl must be provided. This will return a UnifiedConsentByOsanoClient with the ability to submit consents, but not manage subjects. This is suitable for use in a browser environment.

Additionally, the osanoApiKey can be optionally provided to return a UnifiedConsentByOsanoClient with the capability to manage subject profiles. The osanoApiKey value is sensitive, and MUST not be exposed to the client application. For this reason, the osanoApiKey should only be present in the ClientConfig when creating a UnifiedConsentByOsanoClient on the server side.


UnifiedConsentByOsanoSDK.createClient(ClientConfig): UnifiedConsentByOsanoClient


import { UnifiedConsentByOsanoSDK } from 'unifiedconsentbyosano/cmp-javascript-sdk'

const client = UnifiedConsentByOsanoSDK.createClient({
token: accessToken,
apiUrl: '',
osanoApiKey: 'osano-api-key' // Optional. Should only be present on the server side.


Method to register the Privacy Protocols. This method is only available for the browser environment. Parameters: PrivacyProtocolsConfig


UnifiedConsentByOsanoSDK.registerPrivacyProtocols(PrivacyProtocolsConfig): Promise<void>


import { UnifiedConsentByOsanoSDK } from '@unifiedconsentbyosano/cmp-javascript-sdk'

await UnifiedConsentByOsanoSDK.registerPrivacyProtocols(
/** Osano's Unified Consent API URL */
apiUrl: string,
/** Write only api key*/
apiKey: string,
/** Gpc attributes*/
attributes?: Record<string, any>


Creates an EmbeddedHandler instance and initializes the SDK for the embedded experience. This method is only available for the browser environment.

Parameters: EmbeddedConfig


UnifiedConsentByOsanoSDK.initEmbeddedParent(config: EmbeddedConfig): EmbeddedHandler


import { UnifiedConsentByOsanoSDK } from './UnifiedConsentByOsanoSDK'

const embeddedClient = UnifiedConsentByOsanoSDK.initEmbeddedParent({
targetIframe: document.getElementById('iframeId'),



Creates a consent for a subject, using the CreateConsentPayload

Authorization: token
Parameters: CreateConsentPayload
Response: string - The status text of the response

async createConsent(payload: CreateConsentPayload): Promise<string>


Creates a GPC consent for a subject, using the CreateGpcConsentPayload. No actions need to be passed, as the GPC consent configuration is resolved in the Core API.

Authorization: token
Parameters: CreateGpcConsentPayload
Response: string - The status text of the response

async createConsent(payload: CreateConsentPayload): Promise<string>


Retrieves a unified consent for a subject. If a subject ID is passed, then that subject's unified consent will be returned. Otherwise, it will return the unified consent for the currently active subject.

Authorization: token
Parameters: subjectId?: string - Optional. The subject ID to retrieve a unified consent for. If none is passed, the active subjectId will be used.
Response: GetUnifiedConsentResponse

async getUnifiedConsent(subjectId?: string): Promise<GetUnifiedConsentResponse>


Generates and returns a 6-digit profile verification code for a profile by email

Authorization: osanoApiKey
Parameters: email: string - The email to generate a profile verification code for
Response: string - The 6-digit profile verification code

async getProfileVerificationCode(email: string): Promise<string>


Returns true or false if at least one consent exists for the given subject

Authorization: token
Parameters: HasConsentsPayload
Response: boolean

async hasConsents({ subjectId?: string }): Promise<boolean>


Stores the given verified ID and uses it in future subject-aware endpoints like createConsent, getUnifiedConsent, etc to avoid having to pass the subject. This only works in a browser environment.

Authorization: none
Parameters: verifiedId: string - the verifiedId of the subject to login
Response: void

IMPORTANT In order to honor choices made as an anonymous user, mergeAnonymousSubject must be called on the server side BEFORE login is called in the browser.

async login(verifiedId: string): Promise<void>


Removes the associated verified ID and generates an anonymous ID instead to be used in subject-aware endpoints when a subject is not explicitly provided. This only works in a browser environment.

Authorization: none

logout(): void


Merges the consents of the source subject into the target subject.

Authorization: osanoApiKey
Parameters: sourceSubjectId: string - The subject to merge data from, targetSubjectId: string - The subject to merge data to
Response: void

async mergeSubjects(sourceSubjectId: string, targetSubjectId: string): Promise<void>


Creates or updates a user profile in the system and returns their verified ID

Authorization: osanoApiKey
Parameters: SaveProfilePayload
Response: string - The verified ID of the saved profile

async saveProfile({ email: string, profile: any }): Promise<string>


Getter to access the Subject, if provided when instantiated

Response: Subject

subject(): Subject


Recieves a verification code generated with getProfileVerificationCode. Returns the verified id of the subject

Authorization: osanoApiKey
Parameters: VerifySubjectProfilePayload
Response: string - The verified ID of the saved profile

async verifySubjectProfile({ email: string, verificationCode: string }): Promise<string>


A subject represents the person that's giving consent.

A Subject might have two different ids. When they are not identified in the system, this SDK will generate a random UUID to identify the current device. Once the Subject is logged into the system, it can be converted to a verified Subject. A verified Subject has a custom id arbitrarily provided by you.


Creates a Subject with a verified ID from the third party system

::: tip The verified ID should not contain PII or sensitive information :::


static verified({
id: string,
profile?: {
email: string,
firstName?: string,
lastName?: string
}): Subject


const subject = Subject.verified('some-internal-id')


This will generate a subject with an auto-generated UUID

static anonymous(): Subject


const subject = Subject.anonymous()


Handler to send and receive events from a parent window to a child iframe. This client is only available for the browser environment

Types of messages

Messages are specific events that exist only in the browser environment and are triggered when some specific actions are issued in the context of an embedded experience.

Message typeDescriptionPayload
loginTriggered upon successful loginSubject
logoutTriggered upon successful logoutSubject
consent:writeTriggered when a consent is createdAction[]


Receives events from the child iframe and declares its behavior

Parameters: MessageType, MessageListener


on(type: MessageType, listener: MessageListener): void


embeddedClient.on(MessageType.LOGIN, (message) => {
const { subject } =


Sends events to the child iframe


send(message: Message): void


embeddedClient.send({ type: MessageType.LOGIN, data: { subject } })


Gets the domain from the parent window once the handshake between parent and child is completed. Until then, it returns undefined.


getParentDomain(): string | undefined