Welcome

The OneWelcome platform enables users to get and share access all by themselves. We can check in real-time if:

request and user match your access policy
user statements are true (I’m a doctor so give me access)
requests are upon invitation
conditions are met (location, time, ...)
consent for processing personal data has been given

So once you’ve provided us with your access policy, we’re good to go. We will never ask your back-office department to intervene for individual requests. Our validation workflows check statements and conditions through data matching.

Get started now:

Extend your user base with access sharing
Adapt access to your business needs
Reduce administrative burden
Leverage data for innovation
Offer users trust
Eliminate fraud

Onboarding

Getting started with Relationship Management in OneWelcome

OneWelcome account details

For each new OneWelcome customer, a customer instance, called tenant, is created and the following values are communicated to the customer via email:

tenant code, which is used in the API endpoints
Support Desk account

The tenant can be configured via the OneWelcome Config API. Access to this API is granted through an invitation from OneWelcome. OneWelcome will invite a member of your organization to become ‘Security Admin’ for your organization in our system. Upon accepting this role, the Security Admin is free to invite Config Editors (via self-servicing in our Developer Portal, at https://manage.scaledaccess.com) which will receive the claims needed for accessing Config API on behalf of your organization.

How to access the Config API?

Each request to the Config API requires a user access token obtained by a user with the correct admin permissions.

Log in at https://manage.scaledaccess.com with your personal username and password.
Go to Settings and click Advanced Settings.
Copy the displayed user access token. This token is valid for 24 hours.

4. Place the access token in the Authorization Header of subsequent requests to the Config API: - [Consent Config API](#consent-config-api) - [Relationship Config API](#relationship-config-api) - [Authorization Config API](#authorization-config-api) - [Event Stream API](#event-stream-api) - [Logs API](#logs-api)

How to access the Management APIs?

Example: Obtain a user access token with the Authorization Code grant type

step 1A

curl --location --request GET 'https://myauthenticationserver.com/auth?client_id=c96hhv8j7ece9ga4g5wm85m5abwvxr9m&response_type=code&scope=openid&redirect_uri=https://example.com/callback&state=dacfe1341a7d499e88ffa61a0417c1a5&nonce=dd305f270a9f4738899747d0ac56e8e8' \

step 1B

curl --location --request POST "https://myauthenticationserver.com/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --header "Authorization: Basic cjRTd0Zab1NGRG92VGJENmVnbEM4YWNLYXE1VEVBd1FQOmRab3pqeGViY1lWMEdVY0dsSFdTRUJaNHhpOVRobnZTTw==" \
  --data "grant_type=authorization_code&code=cd89d399f60046b20449&redirect_uri=https://example.com/callback \

Send an HTTP request to obtain a user access token from our Authorization API or one of our trusted authorization servers, such as Auth0 and Okta. The access token must apply with the following:
- the issuer and JWKS endpoint have been configured for your tenant,
- the token signature algorithm is ES256 (ECDSA) or RS256 (RSA),
- the sub claim is available, and
- the aud claim is (one of) the allowed audience(s) as configured for your tenant.
Tenant configuration changes can be requested via support@onewelcome.com or can be made by the administrator (only for the Relationship Management API).
Place the access token in the Authorization Header of subsequent requests to the Consent Management API, Relationship Management API, or Mail API.

Integration with Auth0

This how-to helps a new OneWelcome customer up and running by integrating our product with Auth0.

Auth0 is a solution to add authentication and authorization services to your applications. It can be connected with the identity provider of your choice and can be extended with other applications. OneWelcome provides an extension to Auth0 that enables the enrichment of its access tokens with claims based on, for example, your users' relationships (see Relationship-based Access Control). All you need to do, is define a custom Action in the Auth0 dashboard. More integration methods will be added in the near future.

How to add a custom Relationship claim?

Auth0 setup

Step 1. Create a Custom Action

exports.onExecutePostLogin = async (event, api) => {
    const HOOK_URL = "https://hooks.scaledaccess.com";
    const CUSTOM_CLAIM_ID = "https://scaledaccess.com/relationships";
    const { TENANT, APIKEY } = event.secrets;
    const { user_id } = event.user;

    if (!TENANT || !APIKEY) {
        console.error(
            "Please provide a ReBAC tenant and an associated API key."
        );
        return;
    }

    const response = await fetch(`${HOOK_URL}/${TENANT}`, {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            apiKey: APIKEY,
        },
        body: JSON.stringify({ user: { id: user_id } }),
    });

    if (!response.ok) {
        const errorResponse = await response.text();
        console.error(`Could not connect to ${HOOK_URL}.`, errorResponse);
        return;
    }

    const { relationships } = await response.json();

    if (!relationships) {
        console.error(
            `Something went wrong processing the relationships of user with id "${user_id}".`
        );
        return;
    }

    api.accessToken.setCustomClaim(CUSTOM_CLAIM_ID, relationships);
};

Create a new Custom Action in Auth0 to be used in a Post Login Flow.
Go to Actions > Library and click Build Custom.
Choose a name for your Action.
Copy the script on the right in the online editor and paste it on the Create Action page.
Click on Secrets The key icon on the left
Enter the Key and Value for the following secrets (click Add Secret to add multiple entries):
Click Deploy.

Key	Value
`TENANT`	Your tenant code provided by OneWelcome (see OneWelcome account details). This code can be found in manage.scaledaccess.com after your sandbox environment is set up.
`APIKEY`	The API key connected to your OneWelcome tenant. Create and use the apiKey for your tenant (see Setup Webhook Configuration)

Create a Login Flow in Auth0 that uses the Custom Action.
Go to Actions > Flows and click Login.
Drag the Custom Action you have made in the previous step the start and complete steps
Click on Apply

Obtaining and using an enriched access token

Step 3. Request an Auth0 access token

Use your regular method to request an access token.
Confirm that the access token contains the custom claim (e.g. by copying the token into jwt.io).

Step 4. Make access decisions based on Relationships

Use the enriched access token to access a protected resource at your API service.
The API service must provide a mechanism to grant or deny access based on the custom claim.

Testing token enrichment in Postman

This how-to gives detailed instructions on how to use Postman to obtain an Auth0 access token enriched with Relationships of the authenticated user.

Auth0 setup

Step 0. Prepare the client application for Postman callbacks

Add the following URL to the allowed callback URLs for your client application in the Auth0 dashboard: https://getpostman.com/oauth2/callback

Step 1-3. Add the Auth0 Custom Action

Follow the instructions in step 1-3 of How to add a custom Relationship claim to create the Auth0 Custom Action.

Obtaining an enriched access token in Postman

Step 4. Request an Auth0 access token

Start a new request.
Go to the Authorization tab and select type OAuth 2.0.
Click Get New Access Token. A new screen will open.

Fill in the requested parameters as shown below. Make sure to replace the variables with the values found in the Auth0 dashboard.

Parameter	Value
Token Name	(Optional)
Grant Type	Authorization Code
Callback URL	https://{auth0_tenant}.auth0.com/authorize?audience={auth0_audience}
Access Token URL	https://{auth0_tenant}.auth0.com/oauth/token
Client ID	{auth0_client_id}
Client Secret	{auth0_client_secret}
Scope	openid
State	randomstate
Client Authentication	Send as Basic Auth header

Click Request Token.

Integration with Okta

This how-to helps a new OneWelcome customer up and running by integrating our product with Okta.

Okta is a solution to add authentication and authorization services to your applications. It can be connected with the identity provider of your choice and can be extended with other applications. OneWelcome provides an extension to Okta that enables the enrichment of its access tokens with a claim based on your users' relationships (see Relationship-based Access Control). All you need to do, is set up an Okta inline hook.

How to set up the Okta inline hook?

Okta setup

Step 1. Create an inline hook

Log in to your Okta account.
Go to Workflow > Inline Hooks.
Click Add Inline Hook and select Token from the dropdown menu.
Enter the following values:

Field Name	Value	Description
Name	`ReBAC`
URL	`https://hooks.scaledaccess.com/{tenant}/okta`	Your tenant code provided by OneWelcome (see OneWelcome account details). This code can be found in manage.scaledaccess.com after your sandbox environment is set up.
Authentication field	`apiKey`
Authentication secret	The API key connected to your OneWelcome tenant.	Create and use the apiKey for your tenant (see Setup Webhook Configuration)

Click Save.

Step 2. Activate the inline hook

Go to Security > API.
Select the default Authorization Server.
Click Edit.
Go to the Access Policies tab.
For the Default Policy, edit the Default Policy Rule by clicking the pencil icon.
a. In the Use this inline hook field, select ReBAC from the dropdown menu.
b. Click Update Rule.

Obtaining and using an enriched access token

Step 3. Request an Okta access token

Use your regular method to request an access token.
Confirm that the access token contains the scaledaccess_relationships claim (e.g. by copying the token into jwt.io). If the user has no Relationships (yet), the array will be empty.

Step 4. Make access decisions based on Relationships

Use the enriched access token to access a protected resource at your API service.
The API service must provide a mechanism to grant or deny access based on the scaledaccess_relationships claim.

Testing token enrichment in Postman

This how-to gives detailed instructions on how to use Postman to obtain an Okta access token enriched with Relationships of the authenticated user.

Okta setup

Step 1. Create a demo application

Log in to your Okta account.
Go to Applications > Applications and click Add Application.
Click Create New App.
Select Native Service from the Platform dropdown menu.
Click Create.
Name your application, e.g. "OneWelcome Demo".
Click Add URI and enter a dummy URL, e.g. "http://localhost".
Click Save.
Edit the General Settings in the General tab.
a. In the Allowed grant types field, check the Resource Owner Password checkbox.
b. Click Save.

Step 2. Assign the demo application to a test user

Go to Directory > People.
Create a test user.
a. click Add Person.
b. Fill in the form. (For a test user, we recommend to select Set by admin from the Password dropdown menu and to deselect User must change password on first login.)
c. Click Save.
Select the test user.
Click Assign Applications.
Click Assign next to OneWelcome Demo.
Click Save and Go Back.
Click Done.

Obtaining an enriched access token in Postman

Step 3. Request an Okta access token

Start a new request in Postman.
Select POST and enter {issuer_uri}/v1/token in the URL field. The Issuer URI for the default Authorization Server can be found in the Security > API page.
Got to the Body tab and select x-www-form-urlencoded.

Enter the key-value pairs as shown below.

Key	Value
`grant_type`	`password`
`scope`	`openid`
`client_id`	The Client ID* of the "OneWelcome Demo" application.
`username`	The username of the user in step 2.
`password`	The password of the user in step 2.

*The client credentials can be found by selecting the "OneWelcome Demo" in the Applications > Applications page.

Click Send.

Step 4. Check the enriched token

Copy the access token in the response.
Paste the token in jwt.io.
Confirm that the token contains the scaledaccess_relationships claim. If the user has no Relationships (yet), the array will be empty.

Integration with OneWelcome

This how-to helps a new OneWelcome customer up and running by integrating our product with OneWelcome Mobile Identity.

OneWelcome Mobile Identity is a complete solution for Single Sign On (SSO) and customer self-service within your organisation. OneWelcome provides an extension to OneWelcome Mobile Identity that enables the enrichment of its access tokens with a claim based on your users' relationships (see Relationship-based Access Control). All you need to do, is set up a OneWelcome Mobile Identity Web Hook.

How to set up the OneWelcome Mobile Identity Web Hook?

Mobile Identity setup

Step 1. Create a Web Hook

Log in to your Mobile Identity account.
Go to Configuration > System > Web Hooks.
Click Add Web Hook Configuration.
Add the following values to complete the Web Hook setup.

Field Name	Value	Description
Name	`ReBAC`
WebHook type	Customize Token
WebHook base uri	`https://hooks.scaledaccess.com/{tenant}/onewelcome`	Your tenant code provided by OneWelcome (see OneWelcome account details). This code can be found in manage.scaledaccess.com after your sandbox environment is set up.
Authentication method	Basic Authentication
Username	Your tenant code provided by OneWelcome
Password	The API key connected to your OneWelcome tenant.	Create and use the apiKey for your tenant (see Setup Webhook Configuration)

Click Save.

Step 2. Activate the Web Hook

Go to Configuration > Web Clients.
Click Edit on your configured web client.
Find the Customize Access Token Web Hook options and select the ReBAC Web Hook.
Click Save (and Save again to finish editing)

Obtaining and using an enriched access token

Step 3. Request a OneWelcome access token

Use your regular method to request an access token.
Confirm that the access token contains the https://scaledaccess.com/relationships claim (e.g. by copying the token into jwt.io). If the user has no Relationships (yet), the array will be empty.

Step 4. Make access decisions based on Relationships

Use the enriched access token to access a protected resource at your API service.
The API service must provide a mechanism to grant or deny access based on the https://scaledaccess.com/relationships claim.

Integration with Akamai Identity Cloud

This overview shows how OneWelcome customers can integrate Akamai's Identity Management Platform, Identity Cloud, with our Authorization Server, PolicyGate API.

About the PolicyGate API

The OneWelcome products are in compliance with the OAuth 2.0 and OpenID Connect (OIDC) 1.0 standards. Our Authorization Server, PolicyGate API, can be combined with Akamai's Identity Management Platform, Identity Cloud, to form an OIDC Identity Provider with the power to implement strong, centrally governed, token-based access control.

The PolicyGate API's user experience (UX) is realized by a fully customizable widget and this OneWelcome API adds value over Akamai’s Hosted Login option, by focussing on customers that require more features or customization options than supported by the latter. For example, information from a user's digital relationships and previously given consents can be used to define scopes and custom claims in the access tokens issued by the PolicyGate API.

About OAuth 2.0

OAuth 2.0 is a security protocol to protect web APIs. It enables users that control a resource stored by an API Service to delegate access to a software application via an access token. This application (e.g. a mobile app) can then access the resource on behalf of the user, without impersonating them, i.e. without knowing the user's credentials. This process can be divided in three steps:

Authentication of the user: The user proves their identity, for example via their username and password.
Authorization of the application: The software application applies for access via one of the Authorization grant types. If the conditions for the specific request are met, the Authorization Server delivers an access token to the application.
Access to the resource: The application uses the access token to request the resource. The API Service grants or denies access to the resource based on the information in the access token.

The components involved in the authorization process are listed in the following table.

OAuth 2.0 Component	Description
protected resource	A resource that is stored by an API Service, which protects it from unauthorized access.
resource owner	The entity in control of the resource. In most cases the person using the software application.
client application (or OAuth client)	The software application requesting access to the protected resource on behalf of the resource owner.
Authorization Server	The HTTP server that issues tokens to the client application, such as the PolicyGate API.

About OIDC 1.0

OpenID Connect (OIDC) 1.0 is a simple identity layer on top of the OAuth 2.0 protocol that standardizes authentication and the access to identity information of the user. Mostly, the same components as for OAuth 2.0 are in play.

OIDC 1.0 Component	Description
protected resource	The identity information (user profile) which is stored in an Identity Management Platform.
resource owner	The user.
relying party	The client application requesting access to the identity information.
Identity Provider (IdP)	The Authentication Server. In OAuth 2.0 terms this is the Authorization server that makes decisions about who can access identity information, based on the authentication of the user.

Customization of the user journey

The OAuth2 standard recommends the use of the Authorization Code grant type for client applications requesting access tokens on behalf of a user. With this grant type, the user is redirected to authenticate themselves in an external system, such as the OneWelcome widget.

Our widget, or User Experience (UX), is fully customizable. By default, it covers all essential dialogs with which the user supplies their credentials, such as login, registration, and forgot-password flows. These user interaction flows are implemented by Embedded Javascript (EJS) templates that are hosted by OneWelcome. However, the actual content in terms of html, css and js are fetched from your CDN and can be supplied and maintained by your team. It only requires your mobile app or your web server to build on a (public) OIDC library.

With the OneWelcome widget you can:

use your own domain name,
adopt your own styling, wording, and profile attributes,
create application-specific branding based on client ID,
adjust the existing user interaction flows to your needs, and
add data validation.

How to get started?

Please contact us at support@onewelcome.com to access detailed information on how to integrate Akamai Identity Cloud with the PolicyGate API.

Externalized Authorization

The OneWelcome Externalized Authorization feature enables the customer to enforce their business policies uniformly across all their applications.

Overview and Concepts

About Externalized Authorization

A business can specify conditions to determine when to give a user access to their products, i.e. to authorize the user. These conditions form the business policy and can be based on user attributes, product attributes, relationships, user consent, and many other types of information.

Applying a business policy consistently within a microservice-based archictecture poses some challenges: each individual component must know which user is interacting with it and which authorizations are to be granted. To simplify application design and to make applications independent of policy evolutions, authorization can be performed externally. This ensures consistency between applications, in addition to security and scalability.

Externalized Authorization with OneWelcome

OneWelcome offers help with this so-called Externalized Authorization by providing an API-based system to:

Config API: Define customized policies.
Authorization API: Take policies into account to make authorization decisions.

Configuration of Policies: Config API

Information Model

The Config API enables OneWelcome customers, called tenants, to define Policies that can be used by the Authorization API to make authorization decisions for the other OneWelcome APIs and for the tenant's applications.

Objects and Attributes

Policy Name Attribute

Each Policy must be provided with a name that can be linked to the attempted action by following the naming convention: targetType:action.

The most common actions are read, create, update, and delete. The Relationship Management API also makes use of additional actions such as relationships:list.
The type of target ("resource" in the authorization request) can be among others:
- an ActorType, e.g. user,
- a ResourceType, e.g. pet,
- a RelationshipType with the from and to types, e.g. user:is_admin_of:subscription,
- an Invitation (for a specific type of relationship): {fromType}:{relationshipType}:{toType}:invitation e.g. user:is_coadmin_of:subscription:invitation.

Examples of Policies

Policy name	Example Policy content
subscription:read A user attempts to read a specific subscription.	Users can only read subscriptions of which they are admin, co-admin, or member.
user:update A user attempts to change a user attribute, e.g. their phone number.	Users can only update their own User attributes.
user:is_member_of:subscription:invitation:create A user attempts to send (and create) an invitation which invites another user to become a member of a specific subscription.	Users can only create an invitation for a subscription to which they are directly related as admin or co-admin.
user:is_member_of:subscription:invitation:withdraw A user attempts to withdraw an invitation.	Only the invitor of an invitation can withdraw the invitation. An invitation can only be withdrawn as long as it is not yet accepted/rejected.
smart_lock:relationships:list A user attempts to view a list of all the users linked to a smart lock.	Users can only read relationships of a smart lock of which they are admin or co-admin.

The Rego Attribute and the Graphical Representation

The Policy conditions are specified by using the OPA policy language Rego. The Rego data can be entered directly via the Create/update Policy endpoint or can be automatically converted from the graphical representation created in the OneWelcome Relationship Management Portal.

Rego Example

rego: "

package sandbox_small_pond_c0ec.user.is_member_of.subscription.invitation.create

default outcome = "deny"

outcome = "allow" {
  user_is_admin_of_subscription
}
{
  user_is_coadmin_of_subscription
}

user_is_admin_of_subscription {
 input.graph.subject.is_admin_of[_].subscription.id == input.resource.to.id
 input.graph.subject.type == "user"
    }

user_is_coadmin_of_subscription {
 input.graph.subject.is_coadmin_of[_].subscription.id == input.resource.to.id
 input.graph.subject.type == "user"
     }
"

Example of the graphical representation in the OneWelcome Relationship Management portal
The above graph represents the action user:is_member_of:subscription:invitation:create. The converted Rego data of this Policy can be found on the right.

Requirements	Example
The policy target must be present in the policy.	is_member_of
In case of a RelationshipType as policy target, the linked types must be present in the policy.	`from` user `to` subscription
Each ActorType (generally a user) that is allowed to perform the action must be present as a starting element, optionally restricted by a path of required RelationshipTypes towards other Resources/Actors. The latter can include the policy target. Make sure to add a separate starting element for each RelationshipType you wish to include. The amount of starting elements is unlimited.	There are two User starting elements which restrict this action to users with either an is_admin_of or is_coadmin_of Relationships to the target subscription.

Executing Policies: Authorization API

Tenant admins can perform any action in the Relationship Management API, regardless of the defined Policies, when using an access token with the pg:tenant:admin scope.

Information Model

The tenant's applications and the OneWelcome API's can send a request to the Autorization API to execute a Policy and thus determine whether a specific action is authorized. The authorization request is based on the XACML specification which specifies four parts in the request: subject, action, resource, and context. The Authorization API can enrich this input with Relationship information (graph) as provided by the Relationship Management API. All above information can be used to determine the authorization decision based on the corresponding Policy. The response is an object containing the outcome (generally "allow" or "deny") and optionally other data. If the Policy specified in action does not exist, the response is by default "deny".

To make an authorization request, use the following endpoint:

Authorize request

Endpoints Overview

Authorization Config API

List all Policies

Code samples

# You can also use wget
curl -X GET /policies \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /policies HTTP/1.1

acting-tenant-id: string
tenant-id: string


const headers = {
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/policies',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /policies

Lists all defined Policies.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter or no acting tenant
q	query	string	false	Optional search query param for filtering policies based on content.
tenant	path	string	true	Your tenant code.

Responses

Status	Meaning	Description	Schema
200	OK	none	None

Get a Policy

Code samples

# You can also use wget
curl -X GET /policies/{policyName} \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /policies/{policyName} HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/policies/{policyName}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /policies/{policyName}

Returns a specific Policy.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter or no acting tenant
policyName	path	string	true	The identifier for the Policy.
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "name": "string",
  "rego": "string",
  "graph": {}
}

Responses

Status	Meaning	Description	Schema
200	OK	none	PolicyRecordResponse

Create/update Policy

Code samples

# You can also use wget
curl -X PUT /policies/{policyName} \
  -H 'Content-Type: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

PUT /policies/{policyName} HTTP/1.1

Content-Type: application/json

acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "rego": "string",
  "graph": {
    "nodes": [
      {
        "id": "string",
        "name": "string",
        "description": "string",
        "type": {},
        "roles": [
          {}
        ]
      }
    ],
    "links": [
      {
        "id": "string",
        "name": "string",
        "description": "string",
        "sourceId": "string",
        "targetId": "string",
        "roles": [
          "string"
        ]
      }
    ]
  },
  "isReadOnly": true
}';
const headers = {
  'Content-Type':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/policies/{policyName}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /policies/{policyName}

Creates or updates a Policy.

Note: A PUT request overwrites the original object. Be sure to (re-)enter the values for all desired properties.

Body parameter

{
  "rego": "string",
  "graph": {
    "nodes": [
      {
        "id": "string",
        "name": "string",
        "description": "string",
        "type": {},
        "roles": [
          {}
        ]
      }
    ],
    "links": [
      {
        "id": "string",
        "name": "string",
        "description": "string",
        "sourceId": "string",
        "targetId": "string",
        "roles": [
          "string"
        ]
      }
    ]
  },
  "isReadOnly": true
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter or no acting tenant
policyName	path	string	true	The identifier for the Policy.
tenant	path	string	true	Your tenant code.
body	body	UpdatePolicyDataRequest	true	none

Responses

Status	Meaning	Description	Schema
200	OK	none	None

Delete a Policy

Code samples

# You can also use wget
curl -X DELETE /policies/{policyName} \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

DELETE /policies/{policyName} HTTP/1.1

acting-tenant-id: string
tenant-id: string


const headers = {
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/policies/{policyName}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /policies/{policyName}

Removes the Policy specified by {policyName}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter or no acting tenant
policyName	path	string	true	The identifier for the Policy.
tenant	path	string	true	Your tenant code.

Responses

Status	Meaning	Description	Schema
200	OK	none	None

Schemas

PolicyRecordResponse

{
  "name": "string",
  "rego": "string",
  "graph": {}
}

Name	Type	Required	Restrictions	Description
name	string	true	none	The name of the Policy.
rego	string	true	none	The raw Rego policy data.
graph	object	false	none	The graphical representation of the Rego policy.

GraphicalPolicyNodeInput

{
  "id": "string",
  "name": "string",
  "description": "string",
  "type": {},
  "roles": [
    {}
  ]
}

Name	Type	Required	Restrictions	Description
id	string	true	none	none
name	string	true	none	none
description	string	true	none	none
type	object	true	none	none
roles	[object]	true	none	none

GraphicalPolicyLinkInput

{
  "id": "string",
  "name": "string",
  "description": "string",
  "sourceId": "string",
  "targetId": "string",
  "roles": [
    "string"
  ]
}

Name	Type	Required	Restrictions	Description
id	string	true	none	none
name	string	true	none	none
description	string	true	none	none
sourceId	string	true	none	none
targetId	string	true	none	none
roles	[string]	true	none	none

GraphicalPolicyInput

{
  "nodes": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "type": {},
      "roles": [
        {}
      ]
    }
  ],
  "links": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "sourceId": "string",
      "targetId": "string",
      "roles": [
        "string"
      ]
    }
  ]
}

Name	Type	Required	Restrictions	Description
nodes	[GraphicalPolicyNodeInput]	true	none	none
links	[GraphicalPolicyLinkInput]	true	none	none

UpdatePolicyDataRequest

{
  "rego": "string",
  "graph": {
    "nodes": [
      {
        "id": "string",
        "name": "string",
        "description": "string",
        "type": {},
        "roles": [
          {}
        ]
      }
    ],
    "links": [
      {
        "id": "string",
        "name": "string",
        "description": "string",
        "sourceId": "string",
        "targetId": "string",
        "roles": [
          "string"
        ]
      }
    ]
  },
  "isReadOnly": true
}

Name	Type	Required	Restrictions	Description
rego	string	false	none	The raw Rego policy data. Either rego or graph must be provided. If both are provided then graph takes precedence over rego.
graph	GraphicalPolicyInput	false	none	The graphical representation of the Rego policy. The graphical representation will be converted to a Rego policy. Either rego or graph must be provided. If both are provided then graph takes precedence over rego.
isReadOnly	boolean	false	none	none

Authorization API

Authorize request

Code samples

# You can also use wget
curl -X POST https://api.scaledaccess.com/authz/{tenant} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST https://api.scaledaccess.com/authz/{tenant} HTTP/1.1
Host: api.scaledaccess.com
Content-Type: application/json
Accept: application/json

const inputBody = '{
  "subject": {
    "id": "string",
    "type": "string",
    "": "string"
  },
  "action": "string",
  "resource": {
    "": "string"
  },
  "context": {}
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.scaledaccess.com/authz/{tenant}',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /{tenant}

Make an authorization decision based on the configured policies.

Body parameter

{
  "subject": {
    "id": "string",
    "type": "string",
    "": "string"
  },
  "action": "string",
  "resource": {
    "": "string"
  },
  "context": {}
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	none
» subject	body	object	false	The Actor which is attempting the action.
»» id	body	string	false	The identifier of the Actor.
»» type	body	string	false	The type of Actor. This will probably be `user`.
» action	body	string	false	The action to authorize, e.g. `subscription:delete`. The Policy with this name will be executed. If the specified Policy does not exist, the response is by default 'deny'.
» resource	body	object	false	The resource on which the action is attempted. This can be any Resource/Actor defined with the Relationship Management API, or even a resource not known to Scaled Access.
» context	body	object	false	Any additional context that can be used by the policy to determine its decision.
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "outcome": "allow",
  "reason": "string",
  "obligations": [
    "string"
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	Inline
400	Bad Request	Bad request	Inline
403	Forbidden	Forbidden	Inline
404	Not Found	Not found	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» outcome	any	false	none	The outcome of the authorization decision, either a string ('allow' or 'deny') or an object as specified by the policy.
» reason	string	false	none	An optional clarification of the authorization decision.
» obligations	[string]	false	none	An optional list with obligations that must be fulfilled to obtain authorization for the specified action.

Status Code 400

Name	Type	Required	Restrictions	Description
» message	string	false	none	none

Status Code 403

Name	Type	Required	Restrictions	Description
» message	string	false	none	none

Status Code 404

Name	Type	Required	Restrictions	Description
» message	string	false	none	none

The OneWelcome Consent and Preference Management feature enables the customer to define customized consents, specify consent workflows, and register user consents.

Overview and Concepts

Consent is an important concept in the protection of natural persons with regard to the processing of personal data. The specific rules that need to be followed in Europe and for EU citizen data are determined by the General Data Protection Regulation (GDPR). The rules state among others that the controller (e.g. a company offering its services) must be able to demonstrate that the user consented to the processing of their personal data, i.e. the controller must register and keep track of its users' consents.

At OneWelcome, we distinguish between two types of consents:

Consent to a document. Document consents are often required to gain access to a company's service.
Consent to the use of personal data (referred to as "attributes") for a specific purpose. Attribute consents are always optional and indicate a preference of the user.

OneWelcome offers help with Consent and Preference Management by providing a Consent Management API to:

Define customized document and attribute consents.
Register user consents and log each action with regard to these consents.

Configuration of Consents

Information Model

The Consent Management API enables customers, called tenants, to set up consent definitions. Each definition has one or more versions, which contain one or more documents. A distinction is made between objects for document consents and attribute consents. An AttributeConsentDocument can also be referred to as a Policy.

Objects and Properties

Object	Unique identifier	Example	Description
ConsentDefinition	`name`	terms-and-conditions	The (Attribute)ConsentDefinition is a master data object grouping all information about one logical consent. For documents, it indicates whether the consent is `mandatory` for use of the tenant's services. Each ConsentDefinition can have one or more ConsentVersions.
ConsentVersion	`version`	2023.1	The (Attribute)ConsentVersion groups minor revisions of (Attribute)ConsentDocuments for multiple locales. This object also determines the opt-in method for registering consent to these documents and can contain an endOfLife property which specifies when these registered consents expire.
ConsentDocument	`version` /n `language` /n (`listOfAttributes`)	2023.1.1 /n nl-BE /n (email)	The (Attribute)ConsentDocument represents one specific `version` of the actual document (stored in the `url`) or policy (`processingPurpose`) that must be agreed upon by users of a specific locale (`language`) in order to use the tenant's specified service. The moment in time the (Attribute)ConsentDocument can obtain the "valid" state is specified by the `effectiveDate`. /n Policies for Attribute Consents are further identified by the set of personal data (`listOfAttributes`) for which use consent is requested (e.g. email,firstName,phoneNumber). As a result, an AttributeConsentVersion can contain multiple policies with the same processing purpose (e.g. newsletter), but with different options for the data the user shares. Policies also store the `legalBasis` for processing the user's data.

The optInConfig Property

The opt-in configuration specifies how to process new opt-ins, i.e. requests to register a user's consent. There is currently one opt-in method:

Direct opt-in: The request to register a consent is processed immediately.

	User action	Request	Back-end action
1	The user clicks the "I agree" button.	The client requests to register the user's consent: Register my UserConsent	The user's consent is processed (see Registration of User Consents).

The endOfLife Property

To regulate the transition to a new ConsentVersion, an endOfLife can be added to the previous ConsentVersion. This property indicates when the transition starts (startDate) and when documents from the previous version are no longer valid (endDate). The endOfLife also specifies the duration of the period a user gets to agree to the new version (gracePeriod). This grace period starts at the moment the user receives the first invitation to accept the new ConsentDocument.

The actual grace period for a specific user will never extend past the endDate of the endOfLife (see "user B" in the example image below).

Updating Consents

When consent documents require an update, new (Attribute)ConsentDocuments and, for major updates, new (Attribute)ConsentVersions must be created. This results in multiple documents for one locale within the same (Attribute)ConsentDefinition. A set of logical rules determines the state of each of these documents and the action which might be required from the user.

Document states

(Attribute)ConsentDocuments have a status property which indicates whether the document is a draft or is released (active). Documents also have a "lifecycle status" which is determined by a set of conditions (see table). For each locale in an (Attribute)ConsentDefinition, there is one active document, i.e. the document that should currently be offered to (new) users. However, user consents to all currently valid documents grant access to the tenant's service. In contrast, user consents for archived documents are no longer accepted.

Lifecycle status	Requirements
valid	The `effectiveDate` lies in the past. If specified, the `endOfLife.endDate` of the (Attribute)ConsentVersion to which the document belongs, lies in the future. The `status` is not `draft`.
active	The document's `effectiveDate` is the most recent accross all valid (Attribute)ConsentDocuments for the document's locale (`language`) that belong to the same (Attribute)ConsentDefinition.
archived	The `endOfLife.endDate` of the (Attribute)ConsentVersion to which the document belongs, lies in the past.

Managing Updates

Once (Attribute)ConsentDocuments reach their effectiveDate, they can no longer be modified (unless it is a draft). A new (Attribute)ConsentDocument must be created to apply minor (e.g. formulation) or major (content) changes. The below scheme explains how to manage these updates.

Update	Configuration	User action required?
minor	(Attribute)ConsentDocuments with minor differences should be located in the same ConsentVersion. Documents for different locales do not need a simultaneous update.	No. The (Attribute)ConsentDocument for which the user already gave their consent, is still valid. The user may continue using the service.
major	A new (Attribute)ConsentDocument must be created for each locale in a new ConsentVersion.	Yes. Every user must consent to a new (Attribute)ConsentDocument. The transition to the new (Attribute)ConsentVersion makes use of a grace period. During the grace period: The (Attribute)ConsentDocument for which the user already gave their consent, is still valid. The user may continue using the service, but should be reminded of the need to renew their consent. After the grace period: The user's access to the service will be denied until the user agrees to the currently active (Attribute)ConsentDocument. The grace period is defined in the endOfLife of the ConsentVersion to which the previously accepted (Attribute)ConsentDocument belongs.

Example

The above image shows an example of which user consents are required before, during, and after the endOfLife period associated with the ConsentVersion "Green". All users in the example request a Spanish ConsentDocument.

Users A, B, and C already gave their consent for ConsentDocument G1 and are only invited to agree with a new document after startDate.
New users W and X are offered a different ConsentDocument due to the timing of their requests in relation to the effectiveDate of ConsentDocument G3.
New user Y (in contrast to new user Z) still receives a ConsentDocument from the Green ConsentVersion, since the recently created Blue ConsentVersion does not yet have an effective ConsentDocument.
User A gets the full grace period, while user B does not because the remaining time to endDate is less than gracePeriod. User C requests access after endDate and receives no grace period.

Registration of User Consents

Information Model

The Consent Management API handles the actual registration of user consents. When user consents are processed, OneWelcome stores two types of information:

A UserConsent object containing the user's identifier and the properties needed to uniquely identify an (Attribute)ConsentDocument. These objects are used to check whether or not a user gave their consent for a specific document.
An audit-log (RegisterEvent) which stores all user requests and actions for audit purposes.

Conceptual example of audit-log

Time	Consent	User	Action
`2019-11-10T23:00:49Z`	terms_conditions_2019	John Doe	Registered via direct opt-in method.
`2020-01-10T04:50:02Z`	daily_newsletter	Jane Doe	Token requested for double opt-in method.
`2020-01-10T04:55:05Z`	daily_newsletter	Jane Doe	Registered via double opt-in method.
`2020-01-10T20:03:00Z`	terms_conditions_2020	John Doe	Registered via direct opt-in method.
`2020-01-10T20:10:32Z`	terms_conditions_2020	John Doe	Revoked.

Endpoints Overview

The below overview shows the Config and Consent Management endpoints for Document Consents. For Attribute Consents, a similar set of Config endpoints is available.

Default

getJWKS

Code samples

# You can also use wget
curl -X GET /api/v1/.well-known/jwks \
  -H 'Accept: application/json'

GET /api/v1/.well-known/jwks HTTP/1.1

Accept: application/json


const headers = {
  'Accept':'application/json'
};

fetch('/api/v1/.well-known/jwks',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/.well-known/jwks

Example responses

200 Response

{}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Get the active ConsentDocument (Deprecated)

Code samples

# You can also use wget
curl -X GET /api/v1/user-consents/active?name=consent-definition-name&language=EN \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/user-consents/active?name=consent-definition-name&language=EN HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/user-consents/active?name=consent-definition-name&language=EN',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/user-consents/active

DEPRECATED: This endpoint is deprecated and will be removed in a future release. Use one of the following endpoints instead: - GET user-consents/me/active, - GET user-consents/:userId/active, - GET user-consents/:userId/documents/active, or - GET user-consents/:userId/attributes/active. Returns information about the currently active ConsentDocument for the ConsentDefinition name and ConsentDocument language. The active ConsentDocument is the document with the most recent effectiveDate, belonging to a ConsentVersion that is not end-of-life.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
name	query	string	true	The `name` of the (Attribute)ConsentDefinition for which to find the active (Attribute)ConsentDocument.
language	query	string	true	The locale (`language`) for which to find the active (Attribute)ConsentDocument.
tenant	path	string	true	Your tenant code. Mutually exclusive with the tenant header parameter.

Example responses

200 Response

{
  "key": {
    "name": "consent-definition-name",
    "version": "v1.0",
    "document": {
      "version": "docVersion",
      "language": "EN"
    },
    "gracePeriodEnds": "2024-01-31T00:00:00+00:00"
  },
  "data": {
    "consent": {
      "name": "consent-definition-name",
      "displayName": "Example consent definition",
      "mandatory": true,
      "description": "Example ConsentDefinition description"
    },
    "version": {
      "version": "v1.0",
      "displayName": "v1.0",
      "endOfLife": {
        "startDate": "2024-01-31T00:00:00+00:00",
        "endDate": "2024-12-31T00:00:00+00:00",
        "gracePeriod": "P0Y3M0D"
      },
      "optInConfig": [
        {
          "type": "direct"
        }
      ],
      "description": "Example ConsentVersion description"
    },
    "document": {
      "version": "docVersion",
      "displayName": "Example document",
      "language": "EN",
      "effectiveDate": "2019-12-21T10:00:00.000Z",
      "url": "https://www.example.com/documentContent",
      "status": "draft",
      "description": "Example ConsentDocument description",
      "eolStatus": "scheduled"
    }
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ActiveConsentResponse

List all UserConsents for a ConsentDefinition (Deprecated)

Code samples

# You can also use wget
curl -X GET /api/v1/user-consents?name=consent-definition-name \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/user-consents?name=consent-definition-name HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/user-consents?name=consent-definition-name',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/user-consents

DEPRECATED: This endpoint is deprecated and may be replaced in future releases. Future versions might provide separate endpoints for documents and attributes. Returns all (agreed, pending, and rejected) UserConsents for a specific ConsentDefinition. Query parameters can be used to specify the search, for example, to one specific ConsentVersion, language, or ConsentDocument.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
name	query	string	true	The `name` of the (Attribute)ConsentDefinition for which to find UserConsents.
version	query	string	false	The `version` of the (Attribute)ConsentVersion for which to find UserConsents.
documentVersion	query	string	false	The `version` of the (Attribute)ConsentDocument(s) for which to find UserConsents.
documentLanguage	query	string	false	The locale (`language`) of the (Attribute)ConsentDocument(s) for which to find UserConsents.
filter	query	array[string]	false	Filter for the `status` of the UserConsent. By default, "[agreed]".
tenant	path	string	true	Your tenant code. Mutually exclusive with the tenant header parameter.

Enumerated Values

Parameter	Value
filter	agreed
filter	pending
filter	rejected

Example responses

200 Response

{
  "consents": [
    {
      "id": "consent|consent-definition-name|v1.0::docVersion|EN",
      "userId": "user",
      "consent": {
        "name": "consent-definition-name",
        "version": "v1.0",
        "document": {
          "version": "docVersion",
          "language": "EN"
        },
        "status": "agreed",
        "gracePeriodEnds": "2024-01-31T00:00:00+00:00"
      },
      "metaData": {
        "created": 1704038400,
        "lastUpdate": 1704124800
      },
      "client": "client-name",
      "actingUserId": "adminUser"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ConsentListResponse

List my Document UserConsents

Code samples

# You can also use wget
curl -X GET /api/v1/user-consents/me/documents \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/user-consents/me/documents HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/user-consents/me/documents',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/user-consents/me/documents

Lists all UserConsents for Document ConsentDefinitions for the user authenticated by the user access token.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
filter	query	array[string]	false	Filter for the `status` of the UserConsent. By default, "[agreed]".
tenant	path	string	true	Your tenant code. Mutually exclusive with the tenant header parameter.

Enumerated Values

Parameter	Value
filter	agreed
filter	pending
filter	rejected

Example responses

200 Response

{
  "consents": [
    {
      "id": "consent|consent-definition-name|v1.0::docVersion|EN",
      "userId": "user",
      "consent": {
        "name": "consent-definition-name",
        "version": "v1.0",
        "document": {
          "version": "docVersion",
          "language": "EN"
        },
        "status": "agreed",
        "gracePeriodEnds": "2024-01-31T00:00:00+00:00"
      },
      "metaData": {
        "created": 1704038400,
        "lastUpdate": 1704124800
      },
      "client": "client-name",
      "actingUserId": "adminUser"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ConsentListResponse

Register my Document UserConsent

Code samples

# You can also use wget
curl -X POST /api/v1/user-consents/me/documents \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/user-consents/me/documents HTTP/1.1

Content-Type: application/json
Accept: application/json
acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "name": "consent-definition-name",
  "version": "v1.0",
  "status": "agreed",
  "document": {
    "language": "EN",
    "version": "docVersion"
  },
  "confirmationMessage": {
    "channel": "EMAIL",
    "to": {
      "emailTo": "test@example.com"
    },
    "message": {
      "parameters": {}
    }
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/user-consents/me/documents',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/user-consents/me/documents

Registers a new UserConsent for a ConsentDocument for the user authenticated by the user access token. Processing depends on the OptInConfig of the corresponding ConsentVersion:

With type:direct, the UserConsent is registered upon a successful request.
With type:double, a request token is generated and, optionally, sent to the EventHandler. To finalize the registration, the request token must be presented via the Confirm UserConsent endpoint.

Note: In case the access token is an on-behalf-of token, the OptInConfig will be overridden. In the on-behalf-of use case, where a service desk agent performs consent on behalf of the actual consenting user, this API will trigger the sending of a confirmation email to the consenting user. The consenting user will need to click the confirmation link in the email for the consent to be actually registered.

Body parameter

{
  "name": "consent-definition-name",
  "version": "v1.0",
  "status": "agreed",
  "document": {
    "language": "EN",
    "version": "docVersion"
  },
  "confirmationMessage": {
    "channel": "EMAIL",
    "to": {
      "emailTo": "test@example.com"
    },
    "message": {
      "parameters": {}
    }
  }
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
tenant	path	string	true	Your tenant code. Mutually exclusive with the tenant header parameter.
body	body	RegisterConsentRequest	true	none

Example responses

200 Response

{}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Withdraw my Document UserConsent

Code samples

# You can also use wget
curl -X DELETE /api/v1/user-consents/me/documents?id=consent%7Cconsent-definition-name%7Cv1.0%3A%3AdocVersion%7CEN \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

DELETE /api/v1/user-consents/me/documents?id=consent%7Cconsent-definition-name%7Cv1.0%3A%3AdocVersion%7CEN HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/user-consents/me/documents?id=consent%7Cconsent-definition-name%7Cv1.0%3A%3AdocVersion%7CEN',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /api/v1/user-consents/me/documents

Sets the status of the specified UserConsent to rejected. Use the delete query parameter to remove the UserConsent altogether. An audit trail is kept. UserConsents for mandatory ConsentDefinitions cannot be withdrawn.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
id	query	string	true	The identifier for the UserConsent. The `id` can be found via one of the "List UserConsents" endpoints.
delete	query	boolean	false	A boolean indicating whether to remove (hard delete) the UserConsent object. By default, `delete:false`.
tenant	path	string	true	Your tenant code. Mutually exclusive with the tenant header parameter.

Example responses

200 Response

{
  "id": "consent|consent-definition-name|v1.0::docVersion|EN",
  "userId": "user",
  "consent": {
    "name": "consent-definition-name",
    "version": "v1.0",
    "document": {
      "version": "docVersion",
      "language": "EN"
    },
    "gracePeriodEnds": "2024-01-31T00:00:00+00:00"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	UserConsentResponse
400	Bad Request	This consent is not withdrawable because its definition is marked as mandatory	None

List my Attribute UserConsents

Code samples

# You can also use wget
curl -X GET /api/v1/user-consents/me/attributes \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/user-consents/me/attributes HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/user-consents/me/attributes',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/user-consents/me/attributes

Lists all UserConsents for AttributeConsentDefinitions for the user authenticated by the user access token.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
filter	query	array[string]	false	Filter for the `status` of the UserConsent. By default, "[agreed]".
tenant	path	string	true	Your tenant code. Mutually exclusive with the tenant header parameter.

Enumerated Values

Parameter	Value
filter	agreed
filter	pending
filter	rejected

Example responses

200 Response

{
  "consents": [
    {
      "id": "consent|consent-definition-name|v1.0::docVersion|EN",
      "userId": "user",
      "consent": {
        "name": "consent-definition-name",
        "version": "v1.0",
        "document": {
          "version": "docVersion",
          "language": "EN"
        },
        "status": "agreed",
        "gracePeriodEnds": "2024-01-31T00:00:00+00:00"
      },
      "metaData": {
        "created": 1704038400,
        "lastUpdate": 1704124800
      },
      "client": "client-name",
      "actingUserId": "adminUser"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ConsentListResponse

Register my Attribute UserConsent

Code samples

# You can also use wget
curl -X POST /api/v1/user-consents/me/attributes \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/user-consents/me/attributes HTTP/1.1

Content-Type: application/json
Accept: application/json
acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "name": "consent-definition-name",
  "version": "v1.0",
  "status": "agreed",
  "document": {
    "language": "EN",
    "version": "docVersion"
  },
  "confirmationMessage": {
    "channel": "EMAIL",
    "to": {
      "emailTo": "test@example.com"
    },
    "message": {
      "parameters": {}
    }
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/user-consents/me/attributes',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/user-consents/me/attributes

Registers a new UserConsent for an AttributeConsentDocument for the user authenticated by the user access token. Processing depends on the OptInConfig of the corresponding ConsentVersion:

With type:direct, the UserConsent is registered upon a successful request.
With type:double, a request token is generated and, optionally, sent to the EventHandler. To finalize the registration, the request token must be presented via the Confirm UserConsent endpoint.

Body parameter

{
  "name": "consent-definition-name",
  "version": "v1.0",
  "status": "agreed",
  "document": {
    "language": "EN",
    "version": "docVersion"
  },
  "confirmationMessage": {
    "channel": "EMAIL",
    "to": {
      "emailTo": "test@example.com"
    },
    "message": {
      "parameters": {}
    }
  }
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
tenant	path	string	true	Your tenant code. Mutually exclusive with the tenant header parameter.
body	body	RegisterConsentRequest	true	none

Example responses

200 Response

{}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Withdraw my Attribute UserConsent

Code samples

# You can also use wget
curl -X DELETE /api/v1/user-consents/me/attributes?id=consent%7Cconsent-definition-name%7Cv1.0%3A%3AdocVersion%7CEN \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

DELETE /api/v1/user-consents/me/attributes?id=consent%7Cconsent-definition-name%7Cv1.0%3A%3AdocVersion%7CEN HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/user-consents/me/attributes?id=consent%7Cconsent-definition-name%7Cv1.0%3A%3AdocVersion%7CEN',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /api/v1/user-consents/me/attributes

Sets the status of the specified UserConsent to rejected. Use the delete query parameter to remove the UserConsent altogether. An audit trail is kept.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
id	query	string	true	The identifier for the UserConsent. The `id` can be found via one of the "List UserConsents" endpoints.
delete	query	boolean	false	A boolean indicating whether to remove (hard delete) the UserConsent object. By default, `delete:false`.
tenant	path	string	true	Your tenant code. Mutually exclusive with the tenant header parameter.

Example responses

200 Response

{
  "id": "consent|consent-definition-name|v1.0::docVersion|EN",
  "userId": "user",
  "consent": {
    "name": "consent-definition-name",
    "version": "v1.0",
    "document": {
      "version": "docVersion",
      "language": "EN"
    },
    "gracePeriodEnds": "2024-01-31T00:00:00+00:00"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	UserConsentResponse
400	Bad Request	This consent is not withdrawable because its definition is marked as mandatory	None

List my Document UserConsents for all active (or valid) ConsentDocuments

Code samples

# You can also use wget
curl -X GET /api/v1/user-consents/me/documents/active?language=EN \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/user-consents/me/documents/active?language=EN HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/user-consents/me/documents/active?language=EN',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/user-consents/me/documents/active

Lists all currently active ConsentDocuments for the specified locale (language) and, if available, the associated UserConsents for the user authenticated by the user access token. If there is no UserConsent (with status agreed) available for the active document, the valid ConsentDocument(s) for which the user does have a UserConsent are also returned.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
language	query	string	true	Filter for the locale (`language`) of the (Attribute)ConsentDocument.
tenant	path	string	true	Your tenant code. Mutually exclusive with the tenant header parameter.

Example responses

200 Response

{
  "documents": [
    {
      "name": "consent-definition-name",
      "version": "v1.0",
      "mandatory": true,
      "document": {
        "version": "docVersion",
        "language": "EN",
        "effectiveDate": "2019-12-21T10:00:00.000Z",
        "url": "https://www.example.com/documentContent",
        "description": "example ConsentDocument description",
        "processingPurpose": "I consent to the processing of my email address and first name in order to receive the daily newsletter.",
        "displayName": "Example document"
      },
      "userConsent": {
        "id": "consent|consent-definition-name|v1.0::docVersion|EN",
        "userId": "user",
        "status": "agreed",
        "created": "2024-01-31T00:00:00+00:00",
        "lastUpdate": "2024-02-28T00:00:00+00:00",
        "client": "client-name"
      }
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ActiveDocumentsListResponse

List my Attribute UserConsents for all active (or valid) AttributeConsentDocuments

Code samples

# You can also use wget
curl -X GET /api/v1/user-consents/me/attributes/active?language=EN \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/user-consents/me/attributes/active?language=EN HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/user-consents/me/attributes/active?language=EN',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/user-consents/me/attributes/active

Lists all currently active AttributeConsentDocuments for the specified locale (language) and, if available, the associated UserConsents for the user authenticated by the user access token. If there is no UserConsent (with status agreed) available for the active document, the valid AttributeConsentDocument(s) for which the user does have a UserConsent are also returned.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
language	query	string	true	Filter for the locale (`language`) of the (Attribute)ConsentDocument.
tenant	path	string	true	Your tenant code. Mutually exclusive with the tenant header parameter.

Example responses

200 Response

{
  "attributes": [
    {
      "name": "consent-definition-name",
      "version": "v1.0",
      "attribute": {
        "legalBasis": "Consent",
        "version": "docVersion",
        "language": "EN",
        "effectiveDate": "2019-12-21T10:00:00.000Z",
        "processingPurpose": "I consent to the processing of my email address and first name in order to receive the daily newsletter.",
        "listOfAttributes": [
          "attr1",
          "attr2"
        ],
        "displayName": "Example attribute document"
      },
      "userConsent": {
        "id": "consent|consent-definition-name|v1.0::docVersion|EN",
        "userId": "user",
        "status": "agreed",
        "created": "2024-01-31T00:00:00+00:00",
        "lastUpdate": "2024-02-28T00:00:00+00:00",
        "client": "client-name"
      }
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ActiveAttributesListResponse

List a user's Document & Attribute UserConsents

Code samples

# You can also use wget
curl -X GET /api/v1/user-consents/{userId} \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/user-consents/{userId} HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/user-consents/{userId}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/user-consents/{userId}

Lists all UserConsents for Consent Documents & Attributes for the user identified by {userId}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
userId	path	string	true	The identifier of the User.
filter	query	array[string]	false	Filter for the `status` of the UserConsent. By default, "[agreed]".
tenant	path	string	true	Your tenant code. Mutually exclusive with the tenant header parameter.

Enumerated Values

Parameter	Value
filter	agreed
filter	pending
filter	rejected

Example responses

200 Response

{
  "consents": [
    {
      "id": "consent|consent-definition-name|v1.0::docVersion|EN",
      "userId": "user",
      "consent": {
        "name": "consent-definition-name",
        "version": "v1.0",
        "document": {
          "version": "docVersion",
          "language": "EN"
        },
        "status": "agreed",
        "gracePeriodEnds": "2024-01-31T00:00:00+00:00"
      },
      "metaData": {
        "created": 1704038400,
        "lastUpdate": 1704124800
      },
      "client": "client-name",
      "actingUserId": "adminUser"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ConsentListResponse

List a user's Document UserConsents

Code samples

# You can also use wget
curl -X GET /api/v1/user-consents/{userId}/documents \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/user-consents/{userId}/documents HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/user-consents/{userId}/documents',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/user-consents/{userId}/documents

Lists all UserConsents for ConsentDocuments for the user identified by {userId}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
userId	path	string	true	The identifier of the User.
filter	query	array[string]	false	Filter for the `status` of the UserConsent. By default, "[agreed]".
tenant	path	string	true	Your tenant code. Mutually exclusive with the tenant header parameter.

Enumerated Values

Parameter	Value
filter	agreed
filter	pending
filter	rejected

Example responses

200 Response

{
  "consents": [
    {
      "id": "consent|consent-definition-name|v1.0::docVersion|EN",
      "userId": "user",
      "consent": {
        "name": "consent-definition-name",
        "version": "v1.0",
        "document": {
          "version": "docVersion",
          "language": "EN"
        },
        "status": "agreed",
        "gracePeriodEnds": "2024-01-31T00:00:00+00:00"
      },
      "metaData": {
        "created": 1704038400,
        "lastUpdate": 1704124800
      },
      "client": "client-name",
      "actingUserId": "adminUser"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ConsentListResponse

Withdraw a Document UserConsent

Code samples

# You can also use wget
curl -X DELETE /api/v1/user-consents/{userId}/documents?id=consent%7Cconsent-definition-name%7Cv1.0%3A%3AdocVersion%7CEN \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

DELETE /api/v1/user-consents/{userId}/documents?id=consent%7Cconsent-definition-name%7Cv1.0%3A%3AdocVersion%7CEN HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/user-consents/{userId}/documents?id=consent%7Cconsent-definition-name%7Cv1.0%3A%3AdocVersion%7CEN',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /api/v1/user-consents/{userId}/documents

Sets the status of the specified Document UserConsent to rejected. Use the delete query parameter to remove the UserConsent altogether. An audit trail is kept. UserConsents for mandatory ConsentDefinitions cannot be withdrawn.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
id	query	string	true	The identifier for the UserConsent. The `id` can be found via one of the "List UserConsents" endpoints.
delete	query	boolean	false	A boolean indicating whether to remove (hard delete) the UserConsent object. By default, `delete:false`.
userId	path	string	true	The identifier of the User.
tenant	path	string	true	Your tenant code. Mutually exclusive with the tenant header parameter.

Example responses

200 Response

{
  "id": "consent|consent-definition-name|v1.0::docVersion|EN",
  "userId": "user",
  "consent": {
    "name": "consent-definition-name",
    "version": "v1.0",
    "document": {
      "version": "docVersion",
      "language": "EN"
    },
    "gracePeriodEnds": "2024-01-31T00:00:00+00:00"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	UserConsentResponse
400	Bad Request	This consent is not withdrawable because its definition is marked as mandatory	None

Register a Document UserConsent

Code samples

# You can also use wget
curl -X POST /api/v1/user-consents/{userId}/documents \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/user-consents/{userId}/documents HTTP/1.1

Content-Type: application/json
Accept: application/json
acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "name": "consent-definition-name",
  "version": "v1.0",
  "status": "agreed",
  "document": {
    "language": "EN",
    "version": "docVersion"
  },
  "confirmationMessage": {
    "channel": "EMAIL",
    "to": {
      "emailTo": "test@example.com"
    },
    "message": {
      "parameters": {}
    }
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/user-consents/{userId}/documents',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/user-consents/{userId}/documents

Registers a new UserConsent for a ConsentDocument for the user identified by {userId}. Processing depends on the OptInConfig of the corresponding ConsentVersion:

If the OptInConfig type is direct, the UserConsent is directly registered.
If the type is double, a request token is generated and, optionally, sent to the EventHandler. To finalize the registration, the request token must be presented via the Confirm UserConsent endpoint.

Note: In case the access token is an on-behalf-of token, the OptInConfig will be overridden. In the on-behalf-of use case, where a service desk agent performs consent on behalf of the actual consenting user, this API will trigger sending a confirmation email to the consenting user. The consenting user will need to click the confirmation link in the email to have the consent actually registered.

Body parameter

{
  "name": "consent-definition-name",
  "version": "v1.0",
  "status": "agreed",
  "document": {
    "language": "EN",
    "version": "docVersion"
  },
  "confirmationMessage": {
    "channel": "EMAIL",
    "to": {
      "emailTo": "test@example.com"
    },
    "message": {
      "parameters": {}
    }
  }
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
userId	path	string	true	The identifier of the User.
tenant	path	string	true	Your tenant code. Mutually exclusive with the tenant header parameter.
body	body	RegisterConsentRequest	true	none

Example responses

200 Response

{}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

List all Attribute UserConsents for user

Code samples

# You can also use wget
curl -X GET /api/v1/user-consents/{userId}/attributes \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/user-consents/{userId}/attributes HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/user-consents/{userId}/attributes',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/user-consents/{userId}/attributes

Lists all Attribute UserConsents for the user identified by the userId in the path.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
userId	path	string	true	The identifier of the User.
filter	query	array[string]	false	Filter for the `status` of the UserConsent. By default, "[agreed]".
tenant	path	string	true	Your tenant code. Mutually exclusive with the tenant header parameter.

Enumerated Values

Parameter	Value
filter	agreed
filter	pending
filter	rejected

Example responses

200 Response

{
  "consents": [
    {
      "id": "consent|consent-definition-name|v1.0::docVersion|EN",
      "userId": "user",
      "consent": {
        "name": "consent-definition-name",
        "version": "v1.0",
        "document": {
          "version": "docVersion",
          "language": "EN"
        },
        "status": "agreed",
        "gracePeriodEnds": "2024-01-31T00:00:00+00:00"
      },
      "metaData": {
        "created": 1704038400,
        "lastUpdate": 1704124800
      },
      "client": "client-name",
      "actingUserId": "adminUser"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ConsentListResponse

Withdraw an Attribute UserConsent

Code samples

# You can also use wget
curl -X DELETE /api/v1/user-consents/{userId}/attributes?id=consent%7Cconsent-definition-name%7Cv1.0%3A%3AdocVersion%7CEN \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

DELETE /api/v1/user-consents/{userId}/attributes?id=consent%7Cconsent-definition-name%7Cv1.0%3A%3AdocVersion%7CEN HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/user-consents/{userId}/attributes?id=consent%7Cconsent-definition-name%7Cv1.0%3A%3AdocVersion%7CEN',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /api/v1/user-consents/{userId}/attributes

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
id	query	string	true	The identifier for the UserConsent. The `id` can be found via one of the "List UserConsents" endpoints.
delete	query	boolean	false	A boolean indicating whether to remove (hard delete) the UserConsent object. By default, `delete:false`.
userId	path	string	true	The identifier of the User.
tenant	path	string	true	Your tenant code. Mutually exclusive with the tenant header parameter.

Example responses

200 Response

{
  "id": "consent|consent-definition-name|v1.0::docVersion|EN",
  "userId": "user",
  "consent": {
    "name": "consent-definition-name",
    "version": "v1.0",
    "document": {
      "version": "docVersion",
      "language": "EN"
    },
    "gracePeriodEnds": "2024-01-31T00:00:00+00:00"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	UserConsentResponse
400	Bad Request	This consent is not withdrawable because its definition is marked as mandatory	None

Register an Attribute UserConsent

Code samples

# You can also use wget
curl -X POST /api/v1/user-consents/{userId}/attributes \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/user-consents/{userId}/attributes HTTP/1.1

Content-Type: application/json
Accept: application/json
acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "name": "consent-definition-name",
  "version": "v1.0",
  "status": "agreed",
  "document": {
    "language": "EN",
    "version": "docVersion"
  },
  "confirmationMessage": {
    "channel": "EMAIL",
    "to": {
      "emailTo": "test@example.com"
    },
    "message": {
      "parameters": {}
    }
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/user-consents/{userId}/attributes',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/user-consents/{userId}/attributes

Registers a new Attribute UserConsent for the user identified by the userId in the path. Processing depends on the OptInConfig of the corresponding ConsentVersion:

If the OptInConfig type is direct, the UserConsent is directly registered.
If the type is double, a request token is generated and, optionally, sent to the EventHandler. To finalize the registration, the request token must be presented via the Confirm UserConsent endpoint.

Body parameter

{
  "name": "consent-definition-name",
  "version": "v1.0",
  "status": "agreed",
  "document": {
    "language": "EN",
    "version": "docVersion"
  },
  "confirmationMessage": {
    "channel": "EMAIL",
    "to": {
      "emailTo": "test@example.com"
    },
    "message": {
      "parameters": {}
    }
  }
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
userId	path	string	true	The identifier of the User.
tenant	path	string	true	Your tenant code. Mutually exclusive with the tenant header parameter.
body	body	RegisterConsentRequest	true	none

Example responses

200 Response

{}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

List a user's Document UserConsents for all active (or valid) ConsentDocuments

Code samples

# You can also use wget
curl -X GET /api/v1/user-consents/{userId}/documents/active?language=EN \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/user-consents/{userId}/documents/active?language=EN HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/user-consents/{userId}/documents/active?language=EN',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/user-consents/{userId}/documents/active

Lists all currently active ConsentDocuments for the specified locale (language) and, if available, the associated UserConsents for the user identified by {userId}. If there is no UserConsent (with status agreed) available for the active document, the valid ConsentDocument(s) for which the user does have a UserConsent are also returned.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
userId	path	string	true	The identifier of the User.
language	query	string	true	Filter for the locale (`language`) of the (Attribute)ConsentDocument.
tenant	path	string	true	Your tenant code. Mutually exclusive with the tenant header parameter.

Example responses

200 Response

{
  "documents": [
    {
      "name": "consent-definition-name",
      "version": "v1.0",
      "mandatory": true,
      "document": {
        "version": "docVersion",
        "language": "EN",
        "effectiveDate": "2019-12-21T10:00:00.000Z",
        "url": "https://www.example.com/documentContent",
        "description": "example ConsentDocument description",
        "processingPurpose": "I consent to the processing of my email address and first name in order to receive the daily newsletter.",
        "displayName": "Example document"
      },
      "userConsent": {
        "id": "consent|consent-definition-name|v1.0::docVersion|EN",
        "userId": "user",
        "status": "agreed",
        "created": "2024-01-31T00:00:00+00:00",
        "lastUpdate": "2024-02-28T00:00:00+00:00",
        "client": "client-name"
      }
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ActiveDocumentsListResponse

List a user's Attributes UserConsents for all active (or valid) ConsentDocuments

Code samples

# You can also use wget
curl -X GET /api/v1/user-consents/{userId}/attributes/active?language=EN \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/user-consents/{userId}/attributes/active?language=EN HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/user-consents/{userId}/attributes/active?language=EN',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/user-consents/{userId}/attributes/active

Lists all currently active ConsentAttributes for the specified locale (language) and, if available, the associated UserConsents for the user identified by {userId}. If there is no UserConsent (with status agreed) available for the active document, the valid ConsentDocument(s) for which the user does have a UserConsent are also returned.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
userId	path	string	true	The identifier of the User.
language	query	string	true	Filter for the locale (`language`) of the (Attribute)ConsentDocument.
tenant	path	string	true	Your tenant code. Mutually exclusive with the tenant header parameter.

Example responses

200 Response

{
  "attributes": [
    {
      "name": "consent-definition-name",
      "version": "v1.0",
      "attribute": {
        "legalBasis": "Consent",
        "version": "docVersion",
        "language": "EN",
        "effectiveDate": "2019-12-21T10:00:00.000Z",
        "processingPurpose": "I consent to the processing of my email address and first name in order to receive the daily newsletter.",
        "listOfAttributes": [
          "attr1",
          "attr2"
        ],
        "displayName": "Example attribute document"
      },
      "userConsent": {
        "id": "consent|consent-definition-name|v1.0::docVersion|EN",
        "userId": "user",
        "status": "agreed",
        "created": "2024-01-31T00:00:00+00:00",
        "lastUpdate": "2024-02-28T00:00:00+00:00",
        "client": "client-name"
      }
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ActiveAttributesListResponse

Confirm Document UserConsent

Code samples

# You can also use wget
curl -X POST /api/v1/user-consents/confirm/documents \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/user-consents/confirm/documents HTTP/1.1

Content-Type: application/json
Accept: application/json
acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "requestToken": "exampleRequestToken"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/user-consents/confirm/documents',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/user-consents/confirm/documents

Confirms the registration of a Document UserConsent as part of the double opt-in method for registration.

Body parameter

{
  "requestToken": "exampleRequestToken"
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
tenant	path	string	true	Your tenant code. Mutually exclusive with the tenant header parameter.
body	body	ProcessRequestTokenRequest	true	none

Example responses

200 Response

{
  "id": "consent|consent-definition-name|v1.0::docVersion|EN",
  "userId": "user",
  "consent": {
    "name": "consent-definition-name",
    "version": "v1.0",
    "document": {
      "version": "docVersion",
      "language": "EN"
    },
    "gracePeriodEnds": "2024-01-31T00:00:00+00:00"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	UserConsentResponse

Confirm Attribute UserConsent

Code samples

# You can also use wget
curl -X POST /api/v1/user-consents/confirm/attributes \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/user-consents/confirm/attributes HTTP/1.1

Content-Type: application/json
Accept: application/json
acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "requestToken": "exampleRequestToken"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/user-consents/confirm/attributes',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/user-consents/confirm/attributes

Confirms the registration of a Attribute UserConsent as part of the double opt-in method for registration.

Body parameter

{
  "requestToken": "exampleRequestToken"
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
tenant	path	string	true	Your tenant code. Mutually exclusive with the tenant header parameter.
body	body	ProcessRequestTokenRequest	true	none

Example responses

200 Response

{
  "id": "consent|consent-definition-name|v1.0::docVersion|EN",
  "userId": "user",
  "consent": {
    "name": "consent-definition-name",
    "version": "v1.0",
    "document": {
      "version": "docVersion",
      "language": "EN"
    },
    "gracePeriodEnds": "2024-01-31T00:00:00+00:00"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	UserConsentResponse

Code samples

# You can also use wget
curl -X POST /api/v1/user-consents/me/documents/renew-token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/user-consents/me/documents/renew-token HTTP/1.1

Content-Type: application/json
Accept: application/json
acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "name": "consent-definition-name",
  "version": "v1.0",
  "status": "agreed",
  "document": {
    "language": "EN",
    "version": "docVersion"
  },
  "confirmationMessage": {
    "channel": "EMAIL",
    "to": {
      "emailTo": "test@example.com"
    },
    "message": {
      "parameters": {}
    }
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/user-consents/me/documents/renew-token',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/user-consents/me/documents/renew-token

Generates a new request token for renewing document consent for the logged-in user using a double opt-in method. In the case of double opt-in, a confirmation email will be sent to the user. If the access token is an on-behalf-of token, a confirmation email will also be sent to the actual consenting user regardless of the opt-in config type. The user must click the confirmation link in the email to complete the consent registration process.

Body parameter

{
  "name": "consent-definition-name",
  "version": "v1.0",
  "status": "agreed",
  "document": {
    "language": "EN",
    "version": "docVersion"
  },
  "confirmationMessage": {
    "channel": "EMAIL",
    "to": {
      "emailTo": "test@example.com"
    },
    "message": {
      "parameters": {}
    }
  }
}

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
tenant	path	string	true	Your tenant code. Mutually exclusive with the tenant header parameter.
body	body	RegisterConsentRequest	true	none

Example responses

200 Response

{
  "requestToken": "exampleRequestToken"
}

Status	Meaning	Description	Schema
200	OK	none	RequestTokenResponse

Code samples

# You can also use wget
curl -X POST /api/v1/user-consents/{userId}/documents/renew-token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/user-consents/{userId}/documents/renew-token HTTP/1.1

Content-Type: application/json
Accept: application/json
acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "name": "consent-definition-name",
  "version": "v1.0",
  "status": "agreed",
  "document": {
    "language": "EN",
    "version": "docVersion"
  },
  "confirmationMessage": {
    "channel": "EMAIL",
    "to": {
      "emailTo": "test@example.com"
    },
    "message": {
      "parameters": {}
    }
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/user-consents/{userId}/documents/renew-token',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/user-consents/{userId}/documents/renew-token

Generates a new request token for renewing attribute consent for the logged-in user using a double opt-in method. In the case of double opt-in, a confirmation email will be sent to the user. If the access token is an on-behalf-of token, a confirmation email will also be sent to the actual consenting user regardless of the opt-in config type. The user must click the confirmation link in the email to complete the consent registration process.

Body parameter

{
  "name": "consent-definition-name",
  "version": "v1.0",
  "status": "agreed",
  "document": {
    "language": "EN",
    "version": "docVersion"
  },
  "confirmationMessage": {
    "channel": "EMAIL",
    "to": {
      "emailTo": "test@example.com"
    },
    "message": {
      "parameters": {}
    }
  }
}

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
userId	path	string	true	none
tenant	path	string	true	Your tenant code. Mutually exclusive with the tenant header parameter.
body	body	RegisterConsentRequest	true	none

Example responses

200 Response

{
  "requestToken": "exampleRequestToken"
}

Status	Meaning	Description	Schema
200	OK	none	RequestTokenResponse

Code samples

# You can also use wget
curl -X POST /api/v1/user-consents/me/attributes/renew-token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/user-consents/me/attributes/renew-token HTTP/1.1

Content-Type: application/json
Accept: application/json
acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "name": "consent-definition-name",
  "version": "v1.0",
  "status": "agreed",
  "document": {
    "language": "EN",
    "version": "docVersion"
  },
  "confirmationMessage": {
    "channel": "EMAIL",
    "to": {
      "emailTo": "test@example.com"
    },
    "message": {
      "parameters": {}
    }
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/user-consents/me/attributes/renew-token',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/user-consents/me/attributes/renew-token

Generates a new request token for renewing attribute consent for the logged-in user using a double opt-in method.

Body parameter

{
  "name": "consent-definition-name",
  "version": "v1.0",
  "status": "agreed",
  "document": {
    "language": "EN",
    "version": "docVersion"
  },
  "confirmationMessage": {
    "channel": "EMAIL",
    "to": {
      "emailTo": "test@example.com"
    },
    "message": {
      "parameters": {}
    }
  }
}

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
tenant	path	string	true	Your tenant code. Mutually exclusive with the tenant header parameter.
body	body	RegisterConsentRequest	true	none

Example responses

200 Response

{
  "requestToken": "exampleRequestToken"
}

Status	Meaning	Description	Schema
200	OK	none	RequestTokenResponse

Code samples

# You can also use wget
curl -X POST /api/v1/user-consents/{userId}/attributes/renew-token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/user-consents/{userId}/attributes/renew-token HTTP/1.1

Content-Type: application/json
Accept: application/json
acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "name": "consent-definition-name",
  "version": "v1.0",
  "status": "agreed",
  "document": {
    "language": "EN",
    "version": "docVersion"
  },
  "confirmationMessage": {
    "channel": "EMAIL",
    "to": {
      "emailTo": "test@example.com"
    },
    "message": {
      "parameters": {}
    }
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/user-consents/{userId}/attributes/renew-token',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/user-consents/{userId}/attributes/renew-token

Generates a new request token for renewing attribute consent on behalf of another user specified by userId, using a double opt-in method.

Body parameter

{
  "name": "consent-definition-name",
  "version": "v1.0",
  "status": "agreed",
  "document": {
    "language": "EN",
    "version": "docVersion"
  },
  "confirmationMessage": {
    "channel": "EMAIL",
    "to": {
      "emailTo": "test@example.com"
    },
    "message": {
      "parameters": {}
    }
  }
}

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
userId	path	string	true	none
tenant	path	string	true	Your tenant code. Mutually exclusive with the tenant header parameter.
body	body	RegisterConsentRequest	true	none

Example responses

200 Response

{
  "requestToken": "exampleRequestToken"
}

Status	Meaning	Description	Schema
200	OK	none	RequestTokenResponse

Reject Document UserConsent

Code samples

# You can also use wget
curl -X POST /api/v1/user-consents/reject/documents \
  -H 'Content-Type: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/user-consents/reject/documents HTTP/1.1

Content-Type: application/json

acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "requestToken": "exampleRequestToken"
}';
const headers = {
  'Content-Type':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/user-consents/reject/documents',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/user-consents/reject/documents

Rejects the registration of a Document UserConsent as part of the double opt-in method for registration.

Body parameter

{
  "requestToken": "exampleRequestToken"
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
body	body	ProcessRequestTokenRequest	true	none

Responses

Status	Meaning	Description	Schema
204	No Content	none	None

Reject Attribute UserConsent

Code samples

# You can also use wget
curl -X POST /api/v1/user-consents/reject/attributes \
  -H 'Content-Type: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/user-consents/reject/attributes HTTP/1.1

Content-Type: application/json

acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "requestToken": "exampleRequestToken"
}';
const headers = {
  'Content-Type':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/user-consents/reject/attributes',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/user-consents/reject/attributes

Rejects the registration of a Attribute UserConsent as part of the double opt-in method for registration.

Body parameter

{
  "requestToken": "exampleRequestToken"
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
body	body	ProcessRequestTokenRequest	true	none

Responses

Status	Meaning	Description	Schema
204	No Content	none	None

List all ConsentDefinitions

Code samples

# You can also use wget
curl -X GET /api/v1/config/consent-definitions?details=false \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/config/consent-definitions?details=false HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-definitions?details=false',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/config/consent-definitions

Lists all defined ConsentDefinitions.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
details	query	boolean	true	Indicates whether the complete `config` of the requested objects is included in the response.
limit	query	number	false	The maximum number of items returned in one response. When additional items are available, the response contains a `cursor` to request the next batch of items. By default, 100.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.

Example responses

200 Response

{
  "links": {
    "resource1": "https://...",
    "resource2": "https://..."
  },
  "resources": [
    "consent-definition-name"
  ],
  "config": [
    {
      "name": "consent-definition-name",
      "displayName": "Example consent definition",
      "versionsCount": 1,
      "mandatory": true,
      "description": "Example ConsentDefinition description"
    }
  ],
  "cursor": "?cursor=..."
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ConsentDefinitionsResponse
400	Bad Request	The cursor query parameter is invalid.	None

Get ConsentDefinition

Code samples

# You can also use wget
curl -X GET /api/v1/config/consent-definitions/{definitionName} \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/config/consent-definitions/{definitionName} HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-definitions/{definitionName}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/config/consent-definitions/{definitionName}

Returns the ConsentDefinition specified by {definitionName}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.

Example responses

200 Response

{
  "links": {
    "resource1": "https://...",
    "resource2": "https://..."
  },
  "resources": [
    "versions"
  ],
  "config": {
    "name": "consent-definition-name",
    "displayName": "Example consent definition",
    "versionsCount": 1,
    "mandatory": true,
    "description": "Example ConsentDefinition description"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ConsentDefinitionResponse
404	Not Found	The definition does not exist.	None

Create ConsentDefinition

Code samples

# You can also use wget
curl -X POST /api/v1/config/consent-definitions/{definitionName} \
  -H 'Content-Type: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/config/consent-definitions/{definitionName} HTTP/1.1

Content-Type: application/json

acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "mandatory": false,
  "description": "Example ConsentDefinition description",
  "displayName": "Example consent definition"
}';
const headers = {
  'Content-Type':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-definitions/{definitionName}',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/config/consent-definitions/{definitionName}

Creates the ConsentDefinition specified by {definitionName}.

Body parameter

{
  "mandatory": false,
  "description": "Example ConsentDefinition description",
  "displayName": "Example consent definition"
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.
body	body	ConsentDefinitionRequest	true	none

Responses

Status	Meaning	Description	Schema
201	Created	none	None
400	Bad Request	The ConsentDefinition cannot be created because the body does not match the tenant rules or another definition with the same name exists.	None

Upsert ConsentDefinition

Code samples

# You can also use wget
curl -X PUT /api/v1/config/consent-definitions/{definitionName} \
  -H 'Content-Type: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

PUT /api/v1/config/consent-definitions/{definitionName} HTTP/1.1

Content-Type: application/json

acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "mandatory": false,
  "description": "Example ConsentDefinition description",
  "displayName": "Example consent definition"
}';
const headers = {
  'Content-Type':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-definitions/{definitionName}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /api/v1/config/consent-definitions/{definitionName}

Creates or updates the ConsentDefinition specified by {definitionName}.

Note: A PUT request overwrites the original object. Be sure to (re-)enter the values for all desired properties.

Body parameter

{
  "mandatory": false,
  "description": "Example ConsentDefinition description",
  "displayName": "Example consent definition"
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.
body	body	ConsentDefinitionRequest	true	none

Responses

Status	Meaning	Description	Schema
200	OK	none	None
400	Bad Request	The ConsentDefinition cannot be modified because the request body doesn't match the tenant rules or one or more of its versions cannot be modified.	None
404	Not Found	The definition doesn't exist	None

Delete ConsentDefinition

Code samples

# You can also use wget
curl -X DELETE /api/v1/config/consent-definitions/{definitionName} \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

DELETE /api/v1/config/consent-definitions/{definitionName} HTTP/1.1

acting-tenant-id: string
tenant-id: string


const headers = {
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-definitions/{definitionName}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /api/v1/config/consent-definitions/{definitionName}

Deletes the ConsentDefinition specified by {definitionName}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.

Responses

Status	Meaning	Description	Schema
200	OK	none	None
400	Bad Request	The ConsentDefinition cannot be deleted because one or more of its ConsentVersions cannot be modified.	None

List all ConsentVersions

Code samples

# You can also use wget
curl -X GET /api/v1/config/consent-definitions/{definitionName}/versions?details=false \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/config/consent-definitions/{definitionName}/versions?details=false HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-definitions/{definitionName}/versions?details=false',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/config/consent-definitions/{definitionName}/versions

Lists all ConsentVersions of ConsentDefinition {definitionName}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
details	query	boolean	true	Indicates whether the complete `config` of the requested objects is included in the response.
limit	query	number	false	The maximum number of items returned in one response. When additional items are available, the response contains a `cursor` to request the next batch of items. By default, 100.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.

Example responses

200 Response

{
  "links": {
    "resource1": "https://...",
    "resource2": "https://..."
  },
  "resources": [
    "versions"
  ],
  "config": [
    {
      "version": "v1.0",
      "displayName": "v1.0",
      "endOfLife": {
        "startDate": "2024-01-31T00:00:00+00:00",
        "endDate": "2024-12-31T00:00:00+00:00",
        "gracePeriod": "P0Y3M0D"
      },
      "optInConfig": [
        {
          "type": "direct"
        }
      ],
      "documentsCount": 1,
      "description": "Example ConsentVersion description"
    }
  ],
  "cursor": "?cursor=..."
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ConsentVersionsResponse
400	Bad Request	The cursor query parameter is invalid.	None

Get ConsentVersion

Code samples

# You can also use wget
curl -X GET /api/v1/config/consent-definitions/{definitionName}/versions/{version} \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/config/consent-definitions/{definitionName}/versions/{version} HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-definitions/{definitionName}/versions/{version}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/config/consent-definitions/{definitionName}/versions/{version}

Returns the ConsentVersion {version} of ConsentDefinition {definitionName}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.

Example responses

200 Response

{
  "links": {
    "resource1": "https://...",
    "resource2": "https://..."
  },
  "resources": [
    "documents",
    "end-of-life"
  ],
  "config": {
    "version": "v1.0",
    "displayName": "v1.0",
    "endOfLife": {
      "startDate": "2024-01-31T00:00:00+00:00",
      "endDate": "2024-12-31T00:00:00+00:00",
      "gracePeriod": "P0Y3M0D"
    },
    "optInConfig": [
      {
        "type": "direct"
      }
    ],
    "documentsCount": 1,
    "description": "Example ConsentVersion description"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ConsentVersionResponse
404	Not Found	none	None

Create ConsentVersion

Code samples

# You can also use wget
curl -X POST /api/v1/config/consent-definitions/{definitionName}/versions/{version} \
  -H 'Content-Type: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/config/consent-definitions/{definitionName}/versions/{version} HTTP/1.1

Content-Type: application/json

acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "optInConfig": [
    {
      "type": "double",
      "requestTokenConfig": {
        "expiresIn": "P0Y0M7D"
      },
      "messageConfig": {
        "channel": "EMAIL",
        "template": "double-opt-in",
        "emailSubjectLocaleKey": "email-subject.example-key"
      }
    }
  ],
  "description": "Example ConsentVersion description",
  "displayName": "v1.0"
}';
const headers = {
  'Content-Type':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-definitions/{definitionName}/versions/{version}',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/config/consent-definitions/{definitionName}/versions/{version}

Creates the ConsentVersion {version} of ConsentDefinition {definitionName}.

Body parameter

{
  "optInConfig": [
    {
      "type": "double",
      "requestTokenConfig": {
        "expiresIn": "P0Y0M7D"
      },
      "messageConfig": {
        "channel": "EMAIL",
        "template": "double-opt-in",
        "emailSubjectLocaleKey": "email-subject.example-key"
      }
    }
  ],
  "description": "Example ConsentVersion description",
  "displayName": "v1.0"
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.
body	body	ConsentVersionRequest	true	none

Responses

Status	Meaning	Description	Schema
201	Created	none	None
400	Bad Request	The ConsentVersion cannot be created because one or more of its ConsentDocuments cannot be modified.	None

Upsert ConsentVersion

Code samples

# You can also use wget
curl -X PUT /api/v1/config/consent-definitions/{definitionName}/versions/{version} \
  -H 'Content-Type: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

PUT /api/v1/config/consent-definitions/{definitionName}/versions/{version} HTTP/1.1

Content-Type: application/json

acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "optInConfig": [
    {
      "type": "double",
      "requestTokenConfig": {
        "expiresIn": "P0Y0M7D"
      },
      "messageConfig": {
        "channel": "EMAIL",
        "template": "double-opt-in",
        "emailSubjectLocaleKey": "email-subject.example-key"
      }
    }
  ],
  "description": "Example ConsentVersion description",
  "displayName": "v1.0"
}';
const headers = {
  'Content-Type':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-definitions/{definitionName}/versions/{version}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /api/v1/config/consent-definitions/{definitionName}/versions/{version}

Creates or updates the ConsentVersion {version} of ConsentDefinition {definitionName}.

Note: A PUT request overwrites the original object. Be sure to (re-)enter the values for all desired properties.

Body parameter

{
  "optInConfig": [
    {
      "type": "double",
      "requestTokenConfig": {
        "expiresIn": "P0Y0M7D"
      },
      "messageConfig": {
        "channel": "EMAIL",
        "template": "double-opt-in",
        "emailSubjectLocaleKey": "email-subject.example-key"
      }
    }
  ],
  "description": "Example ConsentVersion description",
  "displayName": "v1.0"
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.
body	body	ConsentVersionRequest	true	none

Responses

Status	Meaning	Description	Schema
200	OK	none	None
400	Bad Request	The ConsentVersion cannot be modified because one or more of its ConsentDocuments cannot be modified.	None

Delete ConsentVersion

Code samples

# You can also use wget
curl -X DELETE /api/v1/config/consent-definitions/{definitionName}/versions/{version} \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

DELETE /api/v1/config/consent-definitions/{definitionName}/versions/{version} HTTP/1.1

acting-tenant-id: string
tenant-id: string


const headers = {
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-definitions/{definitionName}/versions/{version}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /api/v1/config/consent-definitions/{definitionName}/versions/{version}

Deletes the ConsentVersion {version} of ConsentDefinition {definitionName}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.

Responses

Status	Meaning	Description	Schema
200	OK	none	None
400	Bad Request	The ConsentVersion cannot be deleted because one or more of its ConsentDocuments cannot be modified.	None

Get endOfLife of ConsentVersion

Code samples

# You can also use wget
curl -X GET /api/v1/config/consent-definitions/{definitionName}/versions/{version}/end-of-life \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/config/consent-definitions/{definitionName}/versions/{version}/end-of-life HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-definitions/{definitionName}/versions/{version}/end-of-life',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/config/consent-definitions/{definitionName}/versions/{version}/end-of-life

Returns the endOfLife associated with the ConsentVersion {version} of ConsentDefinition {definitionName}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.

Example responses

200 Response

{
  "links": {
    "resource1": "https://...",
    "resource2": "https://..."
  },
  "config": {
    "startDate": "2024-01-31T00:00:00+00:00",
    "endDate": "2024-12-31T00:00:00+00:00",
    "gracePeriod": "P0Y3M0D"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ConsentVersionEndOfLifeResponse
404	Not Found	The requested ConsentVersion does not exist or does not have an endOfLife.	None

Upsert EndOfLife of ConsentVersion

Code samples

# You can also use wget
curl -X PUT /api/v1/config/consent-definitions/{definitionName}/versions/{version}/end-of-life \
  -H 'Content-Type: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

PUT /api/v1/config/consent-definitions/{definitionName}/versions/{version}/end-of-life HTTP/1.1

Content-Type: application/json

acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "startDate": "2024-01-31T00:00:00+00:00",
  "endDate": "2024-12-31T00:00:00+00:00",
  "gracePeriod": "P0Y3M0D"
}';
const headers = {
  'Content-Type':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-definitions/{definitionName}/versions/{version}/end-of-life',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /api/v1/config/consent-definitions/{definitionName}/versions/{version}/end-of-life

Creates or updates the endOfLife associated with the ConsentVersion {version} of ConsentDefinition {definitionName}.

Note: A PUT request overwrites the original object. Be sure to (re-)enter the values for all desired properties.

Body parameter

{
  "startDate": "2024-01-31T00:00:00+00:00",
  "endDate": "2024-12-31T00:00:00+00:00",
  "gracePeriod": "P0Y3M0D"
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.
body	body	EndOfLifeRequest	true	none

Responses

Status	Meaning	Description	Schema
200	OK	none	None

Delete EndOfLife of ConsentVersion

Code samples

# You can also use wget
curl -X DELETE /api/v1/config/consent-definitions/{definitionName}/versions/{version}/end-of-life \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

DELETE /api/v1/config/consent-definitions/{definitionName}/versions/{version}/end-of-life HTTP/1.1

acting-tenant-id: string
tenant-id: string


const headers = {
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-definitions/{definitionName}/versions/{version}/end-of-life',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /api/v1/config/consent-definitions/{definitionName}/versions/{version}/end-of-life

Deletes the endOfLife associated with the ConsentVersion {version} of ConsentDefinition {definitionName}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.

Responses

Status	Meaning	Description	Schema
200	OK	none	None

List all ConsentDocument languages

Code samples

# You can also use wget
curl -X GET /api/v1/config/consent-definitions/{definitionName}/versions/{version}/documents?details=false \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/config/consent-definitions/{definitionName}/versions/{version}/documents?details=false HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-definitions/{definitionName}/versions/{version}/documents?details=false',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/config/consent-definitions/{definitionName}/versions/{version}/documents

Lists all locales (language) for which ConsentDocuments exist in ConsentVersion {version} of ConsentDocument {definitionName}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion.
details	query	boolean	true	Indicates whether the complete `config` of the requested objects is included in the response.
limit	query	number	false	The maximum number of items returned in one response. When additional items are available, the response contains a `cursor` to request the next batch of items. By default, 100.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.

Example responses

200 Response

{
  "links": {
    "resource1": "https://...",
    "resource2": "https://..."
  },
  "config": {
    "EN": [
      {
        "version": "docVersionX",
        "displayName": "displayName docVersionX",
        "language": "EN",
        "effectiveDate": "2024-05-10T03:01:44.162Z",
        "url": "https://{host}/termsandconditions.com",
        "status": "active",
        "eolStatus": "valid",
        "description": "description docVersionX"
      }
    ]
  },
  "resources": [
    "EN"
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ConsentDocumentsLanguagesResponse
400	Bad Request	The cursor query parameter is invalid.	None

List all ConsentDocuments for one language

Code samples

# You can also use wget
curl -X GET /api/v1/config/consent-definitions/{definitionName}/versions/{version}/documents/{language}?details=false \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/config/consent-definitions/{definitionName}/versions/{version}/documents/{language}?details=false HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-definitions/{definitionName}/versions/{version}/documents/{language}?details=false',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/config/consent-definitions/{definitionName}/versions/{version}/documents/{language}

Lists all ConsentDocuments in locale {language} in ConsentVersion {version} of ConsentDocument {definitionName}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion.
language	path	string	true	An identifier to specify the locale for which the ConsentDocument applies, e.g. a language code and country/region code.
details	query	boolean	true	Indicates whether the complete `config` of the requested objects is included in the response.
limit	query	number	false	The maximum number of items returned in one response. When additional items are available, the response contains a `cursor` to request the next batch of items. By default, 100.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.

Example responses

200 Response

{
  "links": {
    "resource1": "https://...",
    "resource2": "https://..."
  },
  "resources": [
    "versions"
  ],
  "config": [
    {
      "version": "docVersion",
      "displayName": "Example document",
      "language": "EN",
      "effectiveDate": "2019-12-21T10:00:00.000Z",
      "url": "https://www.example.com/documentContent",
      "status": "draft",
      "description": "Example ConsentDocument description",
      "eolStatus": "scheduled"
    }
  ],
  "cursor": "?cursor=..."
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ConsentDocumentsResponse

Get ConsentDocument

Code samples

# You can also use wget
curl -X GET /api/v1/config/consent-definitions/{definitionName}/versions/{version}/documents/{language}/{documentVersion} \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/config/consent-definitions/{definitionName}/versions/{version}/documents/{language}/{documentVersion} HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-definitions/{definitionName}/versions/{version}/documents/{language}/{documentVersion}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/config/consent-definitions/{definitionName}/versions/{version}/documents/{language}/{documentVersion}

Returns the ConsentDocument specified by locale {language} and version {documentVersion} in ConsentVersion {version} of ConsentDefinition {definitionName}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion.
language	path	string	true	An identifier to specify the locale for which the ConsentDocument applies, e.g. a language code and country/region code.
documentVersion	path	string	true	An identifier for the ConsentDocument. The ConsentDocument is uniquely identified within the context of the ConsentVersion by the combination of its `language` and `version`.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.

Example responses

200 Response

{
  "links": {
    "resource1": "https://...",
    "resource2": "https://..."
  },
  "config": {
    "version": "docVersion",
    "displayName": "Example document",
    "language": "EN",
    "effectiveDate": "2019-12-21T10:00:00.000Z",
    "url": "https://www.example.com/documentContent",
    "status": "draft",
    "description": "Example ConsentDocument description",
    "eolStatus": "scheduled"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ConsentDocumentResponse
404	Not Found	The ConsentDocument does not exist.	None

Create ConsentDocument

Code samples

# You can also use wget
curl -X POST /api/v1/config/consent-definitions/{definitionName}/versions/{version}/documents/{language}/{documentVersion} \
  -H 'Content-Type: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/config/consent-definitions/{definitionName}/versions/{version}/documents/{language}/{documentVersion} HTTP/1.1

Content-Type: application/json

acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "effectiveDate": "2024-01-31T00:00:00+00:00",
  "status": "active",
  "description": "Example ConsentDocument description",
  "url": "https://www.example.com/documentContent",
  "displayName": "Example document"
}';
const headers = {
  'Content-Type':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-definitions/{definitionName}/versions/{version}/documents/{language}/{documentVersion}',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/config/consent-definitions/{definitionName}/versions/{version}/documents/{language}/{documentVersion}

Creates the ConsentDocument specified by locale {language} and version {documentversion} in the ConsentVersion {version} of ConsentDefinition {definitionName}.

Body parameter

{
  "effectiveDate": "2024-01-31T00:00:00+00:00",
  "status": "active",
  "description": "Example ConsentDocument description",
  "url": "https://www.example.com/documentContent",
  "displayName": "Example document"
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion.
language	path	string	true	An identifier to specify the locale for which the ConsentDocument applies, e.g. a language code and country/region code.
documentVersion	path	string	true	An identifier for the ConsentDocument. The ConsentDocument is uniquely identified within the context of the ConsentVersion by the combination of its `language` and `version`.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.
body	body	ConsentDocumentRequest	true	none

Responses

Status	Meaning	Description	Schema
201	Created	none	None
400	Bad Request	The ConsentDocument cannot be modified because the `effectiveDate` is before the current date.	None

Upsert ConsentDocument

Code samples

# You can also use wget
curl -X PUT /api/v1/config/consent-definitions/{definitionName}/versions/{version}/documents/{language}/{documentVersion} \
  -H 'Content-Type: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

PUT /api/v1/config/consent-definitions/{definitionName}/versions/{version}/documents/{language}/{documentVersion} HTTP/1.1

Content-Type: application/json

acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "effectiveDate": "2024-01-31T00:00:00+00:00",
  "status": "active",
  "description": "Example ConsentDocument description",
  "url": "https://www.example.com/documentContent",
  "displayName": "Example document"
}';
const headers = {
  'Content-Type':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-definitions/{definitionName}/versions/{version}/documents/{language}/{documentVersion}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /api/v1/config/consent-definitions/{definitionName}/versions/{version}/documents/{language}/{documentVersion}

Creates or updates the ConsentDocument specified by locale {language} and version {documentversion} in the ConsentVersion {version} of ConsentDefinition {definitionName}.

Note: A PUT request overwrites the original object. Be sure to (re-)enter the values for all desired properties.

Body parameter

{
  "effectiveDate": "2024-01-31T00:00:00+00:00",
  "status": "active",
  "description": "Example ConsentDocument description",
  "url": "https://www.example.com/documentContent",
  "displayName": "Example document"
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion.
language	path	string	true	An identifier to specify the locale for which the ConsentDocument applies, e.g. a language code and country/region code.
documentVersion	path	string	true	An identifier for the ConsentDocument. The ConsentDocument is uniquely identified within the context of the ConsentVersion by the combination of its `language` and `version`.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.
body	body	ConsentDocumentRequest	true	none

Responses

Status	Meaning	Description	Schema
200	OK	none	None
400	Bad Request	The ConsentDocument cannot be modified because the `effectiveDate` is before the current date.	None
404	Not Found	The ConsentDocument does not exist.	None

Delete ConsentDocument

Code samples

# You can also use wget
curl -X DELETE /api/v1/config/consent-definitions/{definitionName}/versions/{version}/documents/{language}/{documentVersion} \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

DELETE /api/v1/config/consent-definitions/{definitionName}/versions/{version}/documents/{language}/{documentVersion} HTTP/1.1

acting-tenant-id: string
tenant-id: string


const headers = {
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-definitions/{definitionName}/versions/{version}/documents/{language}/{documentVersion}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /api/v1/config/consent-definitions/{definitionName}/versions/{version}/documents/{language}/{documentVersion}

Deletes the ConsentDocument specified by locale {language} and version {documentVersion} in the ConsentVersion {version} of ConsentDefinition {definitionName}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion.
language	path	string	true	An identifier to specify the locale for which the ConsentDocument applies, e.g. a language code and country/region code.
documentVersion	path	string	true	An identifier for the ConsentDocument. The ConsentDocument is uniquely identified within the context of the ConsentVersion by the combination of its `language` and `version`.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.

Responses

Status	Meaning	Description	Schema
204	No Content	none	None
400	Bad Request	The ConsentDocument cannot be deleted because the `effectiveDate` is before the current date.	None

List all AttributeConsentDefinitions

Code samples

# You can also use wget
curl -X GET /api/v1/config/consent-attribute-definitions?details=false \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/config/consent-attribute-definitions?details=false HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-attribute-definitions?details=false',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/config/consent-attribute-definitions

Lists all defined AttributeConsentDefinitions.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
details	query	boolean	true	Indicates whether the complete `config` of the requested objects is included in the response.
limit	query	number	false	The maximum number of items returned in one response. When additional items are available, the response contains a `cursor` to request the next batch of items. By default, 100.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.

Example responses

200 Response

{
  "links": {
    "resource1": "https://...",
    "resource2": "https://..."
  },
  "resources": [
    "consent-definition-name"
  ],
  "config": [
    {
      "name": "consent-definition-name",
      "displayName": "Example consent definition",
      "versionsCount": 1,
      "mandatory": true,
      "description": "Example ConsentDefinition description"
    }
  ],
  "cursor": "?cursor=..."
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ConsentDefinitionsResponse
400	Bad Request	The cursor query parameter is invalid.	None

Get AttributeConsentDefinition

Code samples

# You can also use wget
curl -X GET /api/v1/config/consent-attribute-definitions/{definitionName} \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/config/consent-attribute-definitions/{definitionName} HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-attribute-definitions/{definitionName}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/config/consent-attribute-definitions/{definitionName}

Returns the AttributeConsentDefinition specified by {definitionName}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.

Example responses

200 Response

{
  "links": {
    "resource1": "https://...",
    "resource2": "https://..."
  },
  "resources": [
    "versions"
  ],
  "config": {
    "name": "consent-definition-name",
    "displayName": "Example consent definition",
    "versionsCount": 1,
    "mandatory": true,
    "description": "Example ConsentDefinition description"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	AttributeConsentDefinitionResponse
404	Not Found	The definition does not exist.	None

Create AttributeConsentDefinition

Code samples

# You can also use wget
curl -X POST /api/v1/config/consent-attribute-definitions/{definitionName} \
  -H 'Content-Type: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/config/consent-attribute-definitions/{definitionName} HTTP/1.1

Content-Type: application/json

acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "description": "Example ConsentDefinition description",
  "displayName": "Example consent definition"
}';
const headers = {
  'Content-Type':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-attribute-definitions/{definitionName}',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/config/consent-attribute-definitions/{definitionName}

Creates the AttributeConsentDefinition specified by {definitionName}.

Body parameter

{
  "description": "Example ConsentDefinition description",
  "displayName": "Example consent definition"
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.
body	body	AttributeConsentDefinitionRequest	true	none

Responses

Status	Meaning	Description	Schema
201	Created	none	None
400	Bad Request	The AttributeConsentDefinition cannot be created because the body does not match the tenant rules or another definition with the same name exists.	None

Upsert AttributeConsentDefinition

Code samples

# You can also use wget
curl -X PUT /api/v1/config/consent-attribute-definitions/{definitionName} \
  -H 'Content-Type: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

PUT /api/v1/config/consent-attribute-definitions/{definitionName} HTTP/1.1

Content-Type: application/json

acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "description": "Example ConsentDefinition description",
  "displayName": "Example consent definition"
}';
const headers = {
  'Content-Type':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-attribute-definitions/{definitionName}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /api/v1/config/consent-attribute-definitions/{definitionName}

Creates or updates the AttributeConsentDefinition specified by {definitionName}.

Note: A PUT request overwrites the original object. Be sure to (re-)enter the values for all desired properties.

Body parameter

{
  "description": "Example ConsentDefinition description",
  "displayName": "Example consent definition"
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.
body	body	AttributeConsentDefinitionRequest	true	none

Responses

Status	Meaning	Description	Schema
200	OK	none	None
400	Bad Request	The AttributeConsentDefinition cannot be modified because the request body does not match the tenant rules or one or more of its versions cannot be modified.	None
404	Not Found	The definition does not exist.	None

Delete AttributeConsent Definition

Code samples

# You can also use wget
curl -X DELETE /api/v1/config/consent-attribute-definitions/{definitionName} \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

DELETE /api/v1/config/consent-attribute-definitions/{definitionName} HTTP/1.1

acting-tenant-id: string
tenant-id: string


const headers = {
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-attribute-definitions/{definitionName}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /api/v1/config/consent-attribute-definitions/{definitionName}

Deletes the AttributeConsentDefinition specified by {definitionName}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.

Responses

Status	Meaning	Description	Schema
200	OK	none	None
400	Bad Request	The AttributeConsentDefinition cannot be deleted because one or more of its ConsentVersions cannot be modified.	None

List all AttributeConsentVersions

Code samples

# You can also use wget
curl -X GET /api/v1/config/consent-attribute-definitions/{definitionName}/versions?details=false \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/config/consent-attribute-definitions/{definitionName}/versions?details=false HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-attribute-definitions/{definitionName}/versions?details=false',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/config/consent-attribute-definitions/{definitionName}/versions

Lists all AttributeConsentVersions of ConsentDefinition {definitionName}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
details	query	boolean	true	Indicates whether the complete `config` of the requested objects is included in the response.
limit	query	number	false	The maximum number of items returned in one response. When additional items are available, the response contains a `cursor` to request the next batch of items. By default, 100.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.

Example responses

200 Response

{
  "links": {
    "resource1": "https://...",
    "resource2": "https://..."
  },
  "resources": [
    "versions"
  ],
  "config": [
    {
      "version": "v1.0",
      "displayName": "v1.0",
      "endOfLife": {
        "startDate": "2024-01-31T00:00:00+00:00",
        "endDate": "2024-12-31T00:00:00+00:00",
        "gracePeriod": "P0Y3M0D"
      },
      "optInConfig": [
        {
          "type": "direct"
        }
      ],
      "documentsCount": 1,
      "description": "Example ConsentVersion description"
    }
  ],
  "cursor": "?cursor=..."
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ConsentVersionsResponse
400	Bad Request	The cursor query parameter is invalid.	None

Get AttributeConsentVersion

Code samples

# You can also use wget
curl -X GET /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version} \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version} HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}

Returns the AttributeConsentVersion {version} of AttributeConsentDefinition {definitionName}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.

Example responses

200 Response

{
  "links": {
    "resource1": "https://...",
    "resource2": "https://..."
  },
  "resources": [
    "documents",
    "end-of-life"
  ],
  "config": {
    "version": "v1.0",
    "displayName": "v1.0",
    "endOfLife": {
      "startDate": "2024-01-31T00:00:00+00:00",
      "endDate": "2024-12-31T00:00:00+00:00",
      "gracePeriod": "P0Y3M0D"
    },
    "optInConfig": [
      {
        "type": "direct"
      }
    ],
    "documentsCount": 1,
    "description": "Example ConsentVersion description"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ConsentVersionResponse
404	Not Found	none	None

Create AttributeConsentVersion

Code samples

# You can also use wget
curl -X POST /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version} \
  -H 'Content-Type: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version} HTTP/1.1

Content-Type: application/json

acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "optInConfig": [
    {
      "type": "double",
      "requestTokenConfig": {
        "expiresIn": "P0Y0M7D"
      },
      "messageConfig": {
        "channel": "EMAIL",
        "template": "double-opt-in",
        "emailSubjectLocaleKey": "email-subject.example-key"
      }
    }
  ],
  "description": "Example ConsentVersion description",
  "displayName": "v1.0"
}';
const headers = {
  'Content-Type':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}

Creates the AttributeConsentVersion {version} of AttributeConsentDefinition {definitionName}.

Body parameter

{
  "optInConfig": [
    {
      "type": "double",
      "requestTokenConfig": {
        "expiresIn": "P0Y0M7D"
      },
      "messageConfig": {
        "channel": "EMAIL",
        "template": "double-opt-in",
        "emailSubjectLocaleKey": "email-subject.example-key"
      }
    }
  ],
  "description": "Example ConsentVersion description",
  "displayName": "v1.0"
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.
body	body	ConsentVersionRequest	true	none

Responses

Status	Meaning	Description	Schema
201	Created	none	None
400	Bad Request	The AttributeConsentVersion cannot be created because one or more of its ConsentDocuments cannot be modified.	None

Upsert AttributeConsentVersion

Code samples

# You can also use wget
curl -X PUT /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version} \
  -H 'Content-Type: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

PUT /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version} HTTP/1.1

Content-Type: application/json

acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "optInConfig": [
    {
      "type": "double",
      "requestTokenConfig": {
        "expiresIn": "P0Y0M7D"
      },
      "messageConfig": {
        "channel": "EMAIL",
        "template": "double-opt-in",
        "emailSubjectLocaleKey": "email-subject.example-key"
      }
    }
  ],
  "description": "Example ConsentVersion description",
  "displayName": "v1.0"
}';
const headers = {
  'Content-Type':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}

Creates or updates the AttributeConsentVersion {version} of AttributeConsentDefinition {definitionName}.

Note: A PUT request overwrites the original object. Be sure to (re-)enter the values for all desired properties.

Body parameter

{
  "optInConfig": [
    {
      "type": "double",
      "requestTokenConfig": {
        "expiresIn": "P0Y0M7D"
      },
      "messageConfig": {
        "channel": "EMAIL",
        "template": "double-opt-in",
        "emailSubjectLocaleKey": "email-subject.example-key"
      }
    }
  ],
  "description": "Example ConsentVersion description",
  "displayName": "v1.0"
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.
body	body	ConsentVersionRequest	true	none

Responses

Status	Meaning	Description	Schema
200	OK	none	None
400	Bad Request	The AttributeConsentVersion cannot be modified because one or more of its ConsentDocuments cannot be modified.	None
404	Not Found	none	None

Delete AttributeConsentVersion

Code samples

# You can also use wget
curl -X DELETE /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version} \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

DELETE /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version} HTTP/1.1

acting-tenant-id: string
tenant-id: string


const headers = {
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}

Deletes the AttributeConsentVersion {version} of AttributeConsentDefinition {definitionName}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.

Responses

Status	Meaning	Description	Schema
200	OK	none	None
400	Bad Request	The AttributeConsentVersion cannot be deleted because one or more of its ConsentDocuments cannot be modified.	None

Get endOfLife of AttributeConsentVersion

Code samples

# You can also use wget
curl -X GET /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/end-of-life \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/end-of-life HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/end-of-life',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/end-of-life

Returns the endOfLife associated with the AttributeConsentVersion {version} of AttributeConsentDefinition {definitionName}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.

Example responses

200 Response

{
  "links": {
    "resource1": "https://...",
    "resource2": "https://..."
  },
  "config": {
    "startDate": "2024-01-31T00:00:00+00:00",
    "endDate": "2024-12-31T00:00:00+00:00",
    "gracePeriod": "P0Y3M0D"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ConsentVersionEndOfLifeResponse
404	Not Found	The requested ConsentVersion does not exist or does not have an endOfLife.	None

Upsert EndOfLife of AttributeConsentVersion

Code samples

# You can also use wget
curl -X PUT /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/end-of-life \
  -H 'Content-Type: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

PUT /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/end-of-life HTTP/1.1

Content-Type: application/json

acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "startDate": "2024-01-31T00:00:00+00:00",
  "endDate": "2024-12-31T00:00:00+00:00",
  "gracePeriod": "P0Y3M0D"
}';
const headers = {
  'Content-Type':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/end-of-life',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/end-of-life

Creates or updates the endOfLife associated with the AttributeConsentVersion {version} of AttributeConsentDefinition {definitionName}.

Note: A PUT request overwrites the original object. Be sure to (re-)enter the values for all desired properties.

Body parameter

{
  "startDate": "2024-01-31T00:00:00+00:00",
  "endDate": "2024-12-31T00:00:00+00:00",
  "gracePeriod": "P0Y3M0D"
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.
body	body	EndOfLifeRequest	true	none

Responses

Status	Meaning	Description	Schema
200	OK	none	None
400	Bad Request	The existing endOfLife cannot be modified or the new endOfLife cannot be created.	None
404	Not Found	The AttributeConsentVersion does not exist.	None

Delete EndOfLife of AttributeConsentVersion

Code samples

# You can also use wget
curl -X DELETE /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/end-of-life \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

DELETE /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/end-of-life HTTP/1.1

acting-tenant-id: string
tenant-id: string


const headers = {
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/end-of-life',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/end-of-life

Deletes the endOfLife associated with the AttributeConsentVersion {version} of AttributeConsentDefinition {definitionName}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion.
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.

Responses

Status	Meaning	Description	Schema
200	OK	none	None
400	Bad Request	The endOfLife cannot be deleted.	None
404	Not Found	The AttributeConsentVersion does not exist.	None

List all AttributeConsentDocuments

Code samples

# You can also use wget
curl -X GET /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/documents \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/documents HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/documents',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/documents

Lists all defined AttributeConsentDocuments.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion.
details	query	boolean	false	Indicates whether the complete `config` of the requested objects is included in the response.
limit	query	number	false	The maximum number of items returned in one response. When additional items are available, the response contains a `cursor` to request the next batch of items. By default, 100.
title	query	string	false	Filter for the `displayName` of the AttributeConsentDocument. The filtering is case-insensitive and accepts partial matches.
language	query	string	false	Filter for the locale (`language`) of the AttributeConsentDocument.
legalBasis	query	string	false	Filter for the `legalBasis` of the AttributeConsentDocument.
attributes	query	string	false	Filter for the `listOfAttributes` of the AttributeConsentDocument. Provide a comma-separated list. Only AttributeConsentDocuments that match all given attributes are returned.
status	query	string	false	Filter for the `status` of the AttributeConsentDocument.
effectiveDate	query	string	false	Filter for the effectiveDate of the AttributeConsentDocument. Returns all documents with an effectiveDate before the provided dateTime (ISO 8601 format in UTC).
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.

Enumerated Values

Parameter	Value
legalBasis	Consent
legalBasis	Contract
legalBasis	Legal obligation
legalBasis	Legitimate interest
legalBasis	Public task
legalBasis	Vital interest
status	draft
status	active

Example responses

200 Response

{
  "links": {
    "resource1": "https://...",
    "resource2": "https://..."
  },
  "resources": [
    "versions"
  ],
  "config": [
    {
      "legalBasis": "Consent",
      "version": "docVersion",
      "language": "EN",
      "status": "draft",
      "displayName": "Example attribute document",
      "effectiveDate": "2019-12-21T10:00:00.000Z",
      "processingPurpose": "I consent to the processing of my email address and first name in order to receive the daily newsletter.",
      "listOfAttributes": [
        "attr1",
        "attr2"
      ]
    }
  ],
  "cursor": "?cursor=..."
}

Responses

Status	Meaning	Description	Schema
200	OK	none	AttributeConsentDocumentsResponse
400	Bad Request	The cursor query parameter is invalid.	None

Get AttributeConsentDocument

Code samples

# You can also use wget
curl -X GET /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/documents/{documentId} \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/documents/{documentId} HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/documents/{documentId}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/documents/{documentId}

Returns the AttributeConsentDocument specified by {documentId} in AttributeConsentVersion {version} of AttributeConsentDefinition {definitionName}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion.
documentId	path	string	true	The identifier for an AttributeConsentDocument. It follows the format '{documentVersion}
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.

Example responses

200 Response

{
  "links": {
    "resource1": "https://...",
    "resource2": "https://..."
  },
  "config": {
    "legalBasis": "Consent",
    "version": "docVersion",
    "language": "EN",
    "status": "draft",
    "displayName": "Example attribute document",
    "effectiveDate": "2019-12-21T10:00:00.000Z",
    "processingPurpose": "I consent to the processing of my email address and first name in order to receive the daily newsletter.",
    "listOfAttributes": [
      "attr1",
      "attr2"
    ]
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	AttributeConsentDocumentResponse
404	Not Found	The AttributeConsentDocument does not exist.	None

Create AttributeConsentDocument

Code samples

# You can also use wget
curl -X POST /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/documents/{documentId} \
  -H 'Content-Type: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/documents/{documentId} HTTP/1.1

Content-Type: application/json

acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "effectiveDate": "2024-01-31T00:00:00+00:00",
  "status": "active",
  "displayName": "Example attribute document",
  "processingPurpose": "I consent to the processing of my email address and first name in order to receive the daily newsletter.",
  "listOfAttributes": [
    "attr1",
    "attr2"
  ],
  "legalBasis": "Consent"
}';
const headers = {
  'Content-Type':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/documents/{documentId}',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/documents/{documentId}

Creates the AttributeConsentDocument specified by {documentId} in the AttributeConsentVersion {version} of AttributeConsentDefinition {definitionName}.

Body parameter

{
  "effectiveDate": "2024-01-31T00:00:00+00:00",
  "status": "active",
  "displayName": "Example attribute document",
  "processingPurpose": "I consent to the processing of my email address and first name in order to receive the daily newsletter.",
  "listOfAttributes": [
    "attr1",
    "attr2"
  ],
  "legalBasis": "Consent"
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion.
documentId	path	string	true	The identifier for an AttributeConsentDocument. It follows the format '{documentVersion}
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.
body	body	AttributeConsentDocumentRequest	true	none

Responses

Status	Meaning	Description	Schema
201	Created	none	None
400	Bad Request	The AttributeConsentDocument cannot be created because the `effectiveDate` is before the current date.	None

Upsert AttributeConsentDocument

Code samples

# You can also use wget
curl -X PUT /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/documents/{documentId} \
  -H 'Content-Type: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

PUT /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/documents/{documentId} HTTP/1.1

Content-Type: application/json

acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "effectiveDate": "2024-01-31T00:00:00+00:00",
  "status": "active",
  "displayName": "Example attribute document",
  "processingPurpose": "I consent to the processing of my email address and first name in order to receive the daily newsletter.",
  "listOfAttributes": [
    "attr1",
    "attr2"
  ],
  "legalBasis": "Consent"
}';
const headers = {
  'Content-Type':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/documents/{documentId}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/documents/{documentId}

Creates or updates the AttributeConsentDocument specified by {documentId} in the AttributeConsentVersion {version} of AttributeConsentDefinition {definitionName}.

Note: A PUT request overwrites the original object. Be sure to (re-)enter the values for all desired properties.

Body parameter

{
  "effectiveDate": "2024-01-31T00:00:00+00:00",
  "status": "active",
  "displayName": "Example attribute document",
  "processingPurpose": "I consent to the processing of my email address and first name in order to receive the daily newsletter.",
  "listOfAttributes": [
    "attr1",
    "attr2"
  ],
  "legalBasis": "Consent"
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion.
documentId	path	string	true	The identifier for an AttributeConsentDocument. It follows the format '{documentVersion}
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.
body	body	AttributeConsentDocumentRequest	true	none

Responses

Status	Meaning	Description	Schema
200	OK	none	None
400	Bad Request	The AttributeConsentDocument cannot be modified because the `effectiveDate` is before the current date.	None
404	Not Found	The AttributeConsentDocument does not exist.	None

Delete AttributeConsentDocument

Code samples

# You can also use wget
curl -X DELETE /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/documents/{documentId} \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

DELETE /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/documents/{documentId} HTTP/1.1

acting-tenant-id: string
tenant-id: string


const headers = {
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/documents/{documentId}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /api/v1/config/consent-attribute-definitions/{definitionName}/versions/{version}/documents/{documentId}

Deletes the AttributeConsentDocument specified by {documentId} in the AttributeConsentVersion {version} of AttributeConsentDefinition {definitionName}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter and tenant header parameter.
tenant-id	header	string	false	Your tenant code. Mutually exclusive with the tenant path parameter.
definitionName	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion.
documentId	path	string	true	The identifier for an AttributeConsentDocument. It follows the format '{documentVersion}
refresh_user_details	query	boolean	false	Indicates whether the userinfo cache associated with the OneWelcome token is refreshed. By default, `false`.

Responses

Status	Meaning	Description	Schema
204	No Content	none	None
400	Bad Request	The AttributeConsentDocument cannot be deleted because the `effectiveDate` is before the current date.	None

AttributeWithoutStatus

{
  "legalBasis": "Consent",
  "version": "docVersion",
  "language": "EN",
  "effectiveDate": "2019-12-21T10:00:00.000Z",
  "processingPurpose": "I consent to the processing of my email address and first name in order to receive the daily newsletter.",
  "listOfAttributes": [
    "attr1",
    "attr2"
  ],
  "displayName": "Example attribute document"
}

Name	Type	Required	Restrictions	Description
legalBasis	string	true	none	The legal basis for processing the specified personal data, i.e. one of the situations described in Article 6 of the General Data Protection Regulation (GDPR) guidelines.
version	string	true	none	An identifier for the ConsentDocument. The ConsentDocument is uniquely identified within the context of the ConsentVersion by the combination of `language` and `documentVersion`.
language	string	true	none	The language (and/or other characteristics, such as country of residence) used to determine the audience for which the ConsentDocument applies. Each ConsentDocument only has one language.
effectiveDate	string	false	none	A datetime (ISO 8601 format) indicating the moment in time at which the ConsentDocument can become effective and might replace a previous version.
processingPurpose	string	true	none	The purpose for which the user's data is being processed.
listOfAttributes	[string]	true	none	An array of strings representing the attributes for which the user has given consent.
displayName	string	false	none	The display name for the consent.

Enumerated Values

Property	Value
legalBasis	Consent
legalBasis	Contract
legalBasis	Legal obligation
legalBasis	Legitimate interest
legalBasis	Public task
legalBasis	Vital interest

UserDocumentConsentResponse

{
  "id": "consent|consent-definition-name|v1.0::docVersion|EN",
  "userId": "user",
  "status": "agreed",
  "created": "2024-01-31T00:00:00+00:00",
  "lastUpdate": "2024-02-28T00:00:00+00:00",
  "client": "client-name"
}

Name	Type	Required	Restrictions	Description
id	string	true	none	An identifier for the UserConsent.
userId	string	true	none	An identifier for the User to whom the UserConsent applies.
status	string	true	none	The status of the consent, i.e. `agreed`, `pending` or `rejected`.
created	string	true	none	A datetime (ISO 8601 format) indicating the moment in time at which the UserConsent was created.
lastUpdate	string	true	none	A datetime (ISO 8601 format) indicating the moment in time at which the UserConsent was updated.
client	string	false	none	The client id stated in the token that was used to register the UserConsent.

Enumerated Values

Property	Value
status	agreed
status	pending
status	rejected

ActiveAttributeConsentResponse

{
  "name": "consent-definition-name",
  "version": "v1.0",
  "attribute": {
    "legalBasis": "Consent",
    "version": "docVersion",
    "language": "EN",
    "effectiveDate": "2019-12-21T10:00:00.000Z",
    "processingPurpose": "I consent to the processing of my email address and first name in order to receive the daily newsletter.",
    "listOfAttributes": [
      "attr1",
      "attr2"
    ],
    "displayName": "Example attribute document"
  },
  "userConsent": {
    "id": "consent|consent-definition-name|v1.0::docVersion|EN",
    "userId": "user",
    "status": "agreed",
    "created": "2024-01-31T00:00:00+00:00",
    "lastUpdate": "2024-02-28T00:00:00+00:00",
    "client": "client-name"
  }
}

Name	Type	Required	Restrictions	Description
name	string	true	none	The `name` of the ConsentDefinition to which the ConsentDocument belongs.
version	string	true	none	The `version` of the ConsentVersion to which the ConsentDocument belongs.
attribute	AttributeWithoutStatus	true	none	The AttributeConsentDocument.
userConsent	UserDocumentConsentResponse	false	none	The UserConsent associated with the specified ConsentDocument.

GetActiveConsentQueryParams

{
  "name": "consent-definition-name",
  "language": "EN"
}

Name	Type	Required	Restrictions	Description
name	string	true	none	The `name` of the (Attribute)ConsentDefinition for which to find the active (Attribute)ConsentDocument.
language	string	true	none	The locale (`language`) for which to find the active (Attribute)ConsentDocument.

DocumentResponse

{
  "version": "docVersion",
  "language": "EN"
}

Name	Type	Required	Restrictions	Description
version	string	true	none	The `version` of the (Attribute)ConsentDocument.
language	string	true	none	The locale (`language`) of the (Attribute)ConsentDocument.

ConsentResponseWithoutStatus

{
  "name": "consent-definition-name",
  "version": "v1.0",
  "document": {
    "version": "docVersion",
    "language": "EN"
  },
  "gracePeriodEnds": "2024-01-31T00:00:00+00:00"
}

Name	Type	Required	Restrictions	Description
name	string	true	none	The `name` of the (Attribute)ConsentDefinition to which the (Attribute)ConsentDocument belongs.
version	string	true	none	The `version` of the (Attribute)ConsentVersion to which the (Attribute)ConsentDocument belongs.
document	DocumentResponse	true	none	The properties of the (Attribute)ConsentDocument.
gracePeriodEnds	string	false	none	A datetime (ISO 8601 format) indicating the moment in time at which the consent is no longer valid. This moment is determined by the `gracePeriod` of the endOfLife associated with the ConsentVersion and cannot be later than the endOfLife's `endDate`.

ConsentDefinitionWithoutCount

{
  "name": "consent-definition-name",
  "displayName": "Example consent definition",
  "mandatory": true,
  "description": "Example ConsentDefinition description"
}

Name	Type	Required	Restrictions	Description
name	string	true	none	The identifier for the ConsentDefinition.
displayName	string	false	none	The human-readable name for the ConsentDefinition.
mandatory	boolean	true	none	Indicates whether the ConsentDefinition is mandatory.
description	string	false	none	A description for the ConsentDefinition.

EndOfLifeRequest

{
  "startDate": "2024-01-31T00:00:00+00:00",
  "endDate": "2024-12-31T00:00:00+00:00",
  "gracePeriod": "P0Y3M0D"
}

Name	Type	Required	Restrictions	Description
startDate	string	true	none	The "sunset date", i.e. a datetime (ISO 8601 format) indicating the first moment in time that users can receive notifications to report the termination of the associated ConsentVersion. This notification should include an invitation to accept the new version of the consent. `startDate` can only be set to a future moment in time and must lie before `endDate`.
endDate	string	true	none	The "archive date", i.e. a datetime (ISO 8601 format) indicating the last moment in time that a ConsentDocument of the associated ConsentVersion can be valid.
gracePeriod	string	true	none	A duration (ISO 8601 Duration format) indicating the period the user gets to agree to the new active ConsentDocument. This period starts the moment the user receives the first invitation to accept this new ConsentDocument. The actual grace period for a specific user is never extended beyond the `endDate`.

OptInConfig

{
  "type": "direct"
}

Name	Type	Required	Restrictions	Description
type	string	true	none	The opt-in method applicable to the ConsentVersion.

Enumerated Values

Property	Value
type	direct
type	double

ConsentVersionWithoutCount

{
  "version": "v1.0",
  "displayName": "v1.0",
  "endOfLife": {
    "startDate": "2024-01-31T00:00:00+00:00",
    "endDate": "2024-12-31T00:00:00+00:00",
    "gracePeriod": "P0Y3M0D"
  },
  "optInConfig": [
    {
      "type": "direct"
    }
  ],
  "description": "Example ConsentVersion description"
}

Name	Type	Required	Restrictions	Description
version	string	true	none	The identifier for the ConsentVersion.
displayName	string	false	none	The human-readable name for the ConsentVersion.
endOfLife	EndOfLifeRequest	false	none	The endOfLife object which manages the termination of the ConsentVersion.
optInConfig	[OptInConfig]	true	none	The opt-in configuration for the ConsentVersion.
description	string	false	none	A description for the ConsentVersion.

ConsentDocument

{
  "version": "docVersion",
  "displayName": "Example document",
  "language": "EN",
  "effectiveDate": "2019-12-21T10:00:00.000Z",
  "url": "https://www.example.com/documentContent",
  "status": "draft",
  "description": "Example ConsentDocument description",
  "eolStatus": "scheduled"
}

Name	Type	Required	Restrictions	Description
version	string	true	none	An identifier for the ConsentDocument. The ConsentDocument is uniquely identified within the context of the ConsentVersion by the combination of its `language` and `version`.
displayName	string	false	none	The human-readable name for the ConsentDocument.
language	string	true	none	The locale for which the ConsentDocument applies, e.g. a language code and country/region code. Each ConsentDocument only has one `language`.
effectiveDate	string	false	none	A datetime (ISO 8601 format) indicating the moment in time at which the ConsentDocument can become effective and might replace a previous version.
url	string	false	none	A URL which can be used to share the content of the ConsentDocument with the user.
status	string	true	none	The status of the ConsentDocument.
description	string	false	none	A description for the ConsentDocument.
eolStatus	string	false	none	The status of the end-of-life configuration of this ConsentDocument (if present)

Enumerated Values

Property	Value
status	draft
status	active
eolStatus	scheduled
eolStatus	draft
eolStatus	active
eolStatus	valid
eolStatus	inactive

FullConsentResponse

{
  "consent": {
    "name": "consent-definition-name",
    "displayName": "Example consent definition",
    "mandatory": true,
    "description": "Example ConsentDefinition description"
  },
  "version": {
    "version": "v1.0",
    "displayName": "v1.0",
    "endOfLife": {
      "startDate": "2024-01-31T00:00:00+00:00",
      "endDate": "2024-12-31T00:00:00+00:00",
      "gracePeriod": "P0Y3M0D"
    },
    "optInConfig": [
      {
        "type": "direct"
      }
    ],
    "description": "Example ConsentVersion description"
  },
  "document": {
    "version": "docVersion",
    "displayName": "Example document",
    "language": "EN",
    "effectiveDate": "2019-12-21T10:00:00.000Z",
    "url": "https://www.example.com/documentContent",
    "status": "draft",
    "description": "Example ConsentDocument description",
    "eolStatus": "scheduled"
  }
}

Name	Type	Required	Restrictions	Description
consent	ConsentDefinitionWithoutCount	true	none	none
version	ConsentVersionWithoutCount	true	none	none
document	ConsentDocument	true	none	none

ActiveConsentResponse

{
  "key": {
    "name": "consent-definition-name",
    "version": "v1.0",
    "document": {
      "version": "docVersion",
      "language": "EN"
    },
    "gracePeriodEnds": "2024-01-31T00:00:00+00:00"
  },
  "data": {
    "consent": {
      "name": "consent-definition-name",
      "displayName": "Example consent definition",
      "mandatory": true,
      "description": "Example ConsentDefinition description"
    },
    "version": {
      "version": "v1.0",
      "displayName": "v1.0",
      "endOfLife": {
        "startDate": "2024-01-31T00:00:00+00:00",
        "endDate": "2024-12-31T00:00:00+00:00",
        "gracePeriod": "P0Y3M0D"
      },
      "optInConfig": [
        {
          "type": "direct"
        }
      ],
      "description": "Example ConsentVersion description"
    },
    "document": {
      "version": "docVersion",
      "displayName": "Example document",
      "language": "EN",
      "effectiveDate": "2019-12-21T10:00:00.000Z",
      "url": "https://www.example.com/documentContent",
      "status": "draft",
      "description": "Example ConsentDocument description",
      "eolStatus": "scheduled"
    }
  }
}

Name	Type	Required	Restrictions	Description
key	ConsentResponseWithoutStatus	true	none	none
data	FullConsentResponse	true	none	none

ConsentResponse

{
  "name": "consent-definition-name",
  "version": "v1.0",
  "document": {
    "version": "docVersion",
    "language": "EN"
  },
  "status": "agreed",
  "gracePeriodEnds": "2024-01-31T00:00:00+00:00"
}

Name	Type	Required	Restrictions	Description
name	string	true	none	The `name` of the (Attribute)ConsentDefinition to which the (Attribute)ConsentDocument belongs.
version	string	true	none	The `version` of the (Attribute)ConsentVersion to which the (Attribute)ConsentDocument belongs.
document	DocumentResponse	true	none	The properties of the (Attribute)ConsentDocument.
status	string	true	none	The status of the consent, i.e. `agreed`, `pending` or `rejected`.
gracePeriodEnds	string	false	none	A datetime (ISO 8601 format) indicating the moment in time at which the consent is no longer valid. This moment is determined by the `gracePeriod` of the endOfLife associated with the ConsentVersion and cannot be later than the endOfLife's `endDate`.

Enumerated Values

Property	Value
status	agreed
status	pending
status	rejected

MetaData

{
  "created": 1704038400,
  "lastUpdate": 1704124800
}

Name	Type	Required	Restrictions	Description
created	number	true	none	A Unix timestamp indicating the moment in time at which the UserConsent was created.
lastUpdate	number	true	none	A Unix timestamp indicating the last moment in time at which the UserConsent was updated.

ConsentListElementResponse

{
  "id": "consent|consent-definition-name|v1.0::docVersion|EN",
  "userId": "user",
  "consent": {
    "name": "consent-definition-name",
    "version": "v1.0",
    "document": {
      "version": "docVersion",
      "language": "EN"
    },
    "status": "agreed",
    "gracePeriodEnds": "2024-01-31T00:00:00+00:00"
  },
  "metaData": {
    "created": 1704038400,
    "lastUpdate": 1704124800
  },
  "client": "client-name",
  "actingUserId": "adminUser"
}

Name	Type	Required	Restrictions	Description
id	string	true	none	An identifier for the UserConsent.
userId	string	true	none	An identifier for the User to whom the UserConsent applies.
consent	ConsentResponse	true	none	The properties of the Consent.
metaData	MetaData	true	none	Metadata concerning the UserConsent.
client	string	true	none	The client.
actingUserId	string	false	none	An identifier for the User who acted on behalf of the consenting user

ConsentListResponse

{
  "consents": [
    {
      "id": "consent|consent-definition-name|v1.0::docVersion|EN",
      "userId": "user",
      "consent": {
        "name": "consent-definition-name",
        "version": "v1.0",
        "document": {
          "version": "docVersion",
          "language": "EN"
        },
        "status": "agreed",
        "gracePeriodEnds": "2024-01-31T00:00:00+00:00"
      },
      "metaData": {
        "created": 1704038400,
        "lastUpdate": 1704124800
      },
      "client": "client-name",
      "actingUserId": "adminUser"
    }
  ]
}

Name	Type	Required	Restrictions	Description
consents	[ConsentListElementResponse]	true	none	A list of UserConsents.

GetConsentQueryParams

{
  "filter": [
    "agreed"
  ]
}

Name	Type	Required	Restrictions	Description
filter	[string]	false	none	Filter for the `status` of the UserConsent. By default, "[agreed]".

DocumentWithoutStatus

{
  "version": "docVersion",
  "language": "EN",
  "effectiveDate": "2019-12-21T10:00:00.000Z",
  "url": "https://www.example.com/documentContent",
  "description": "example ConsentDocument description",
  "processingPurpose": "I consent to the processing of my email address and first name in order to receive the daily newsletter.",
  "displayName": "Example document"
}

Name	Type	Required	Restrictions	Description
version	string	true	none	An identifier for the ConsentDocument. The ConsentDocument is uniquely identified within the context of the ConsentVersion by the combination of `language` and `documentVersion`.
language	string	true	none	The language (and/or other characteristics, such as country of residence) used to determine the audience for which the ConsentDocument applies. Each ConsentDocument only has one language.
effectiveDate	string	false	none	A datetime (ISO 8601 format) indicating the moment in time at which the ConsentDocument can become effective and might replace a previous version.
url	string	false	none	A URL which can be used to share the content of the ConsentDocument with the user.
description	string	false	none	A description for the ConsentDocument.
processingPurpose	string	false	none	Only available for attribute documents
displayName	string	false	none	The human-readable name for the ConsentDocument.

ActiveDocumentConsentResponse

{
  "name": "consent-definition-name",
  "version": "v1.0",
  "mandatory": true,
  "document": {
    "version": "docVersion",
    "language": "EN",
    "effectiveDate": "2019-12-21T10:00:00.000Z",
    "url": "https://www.example.com/documentContent",
    "description": "example ConsentDocument description",
    "processingPurpose": "I consent to the processing of my email address and first name in order to receive the daily newsletter.",
    "displayName": "Example document"
  },
  "userConsent": {
    "id": "consent|consent-definition-name|v1.0::docVersion|EN",
    "userId": "user",
    "status": "agreed",
    "created": "2024-01-31T00:00:00+00:00",
    "lastUpdate": "2024-02-28T00:00:00+00:00",
    "client": "client-name"
  }
}

Name	Type	Required	Restrictions	Description
name	string	true	none	The `name` of the ConsentDefinition to which the ConsentDocument belongs.
version	string	true	none	The `version` of the ConsentVersion to which the ConsentDocument belongs.
mandatory	boolean	true	none	Indicates whether the ConsentDefinition to which the ConsentDocument belongs is mandatory.
document	DocumentWithoutStatus	true	none	The ConsentDocument.
userConsent	UserDocumentConsentResponse	false	none	The UserConsent associated with the specified ConsentDocument.

ActiveConsentListResponse

{
  "documents": [
    {
      "name": "consent-definition-name",
      "version": "v1.0",
      "mandatory": true,
      "document": {
        "version": "docVersion",
        "language": "EN",
        "effectiveDate": "2019-12-21T10:00:00.000Z",
        "url": "https://www.example.com/documentContent",
        "description": "example ConsentDocument description",
        "processingPurpose": "I consent to the processing of my email address and first name in order to receive the daily newsletter.",
        "displayName": "Example document"
      },
      "userConsent": {
        "id": "consent|consent-definition-name|v1.0::docVersion|EN",
        "userId": "user",
        "status": "agreed",
        "created": "2024-01-31T00:00:00+00:00",
        "lastUpdate": "2024-02-28T00:00:00+00:00",
        "client": "client-name"
      }
    }
  ],
  "attributes": [
    {
      "name": "consent-definition-name",
      "version": "v1.0",
      "attribute": {
        "legalBasis": "Consent",
        "version": "docVersion",
        "language": "EN",
        "effectiveDate": "2019-12-21T10:00:00.000Z",
        "processingPurpose": "I consent to the processing of my email address and first name in order to receive the daily newsletter.",
        "listOfAttributes": [
          "attr1",
          "attr2"
        ],
        "displayName": "Example attribute document"
      },
      "userConsent": {
        "id": "consent|consent-definition-name|v1.0::docVersion|EN",
        "userId": "user",
        "status": "agreed",
        "created": "2024-01-31T00:00:00+00:00",
        "lastUpdate": "2024-02-28T00:00:00+00:00",
        "client": "client-name"
      }
    }
  ]
}

Name	Type	Required	Restrictions	Description
documents	[ActiveDocumentConsentResponse]	true	none	A list of all currently active ConsentDocuments for the specified locale (`language`) and, if available, the associated UserConsents for the specified user. When the user only has a UserConsent with status `agreed` for a valid ConsentDocument (i.e. not for the active document), this ConsentDocument is also returned.
attributes	[ActiveAttributeConsentResponse]	true	none	A list of all currently active AttributeConsentDocuments for the specified locale (`language`) and, if available, the associated UserConsents for the specified user. When the user only has a UserConsent with status `agreed` for a valid AttributeConsentDocument (i.e. not for the active document), this AttributeConsentDocument is also returned.

ActiveDocumentsListResponse

{
  "documents": [
    {
      "name": "consent-definition-name",
      "version": "v1.0",
      "mandatory": true,
      "document": {
        "version": "docVersion",
        "language": "EN",
        "effectiveDate": "2019-12-21T10:00:00.000Z",
        "url": "https://www.example.com/documentContent",
        "description": "example ConsentDocument description",
        "processingPurpose": "I consent to the processing of my email address and first name in order to receive the daily newsletter.",
        "displayName": "Example document"
      },
      "userConsent": {
        "id": "consent|consent-definition-name|v1.0::docVersion|EN",
        "userId": "user",
        "status": "agreed",
        "created": "2024-01-31T00:00:00+00:00",
        "lastUpdate": "2024-02-28T00:00:00+00:00",
        "client": "client-name"
      }
    }
  ]
}

Name	Type	Required	Restrictions	Description
documents	[ActiveDocumentConsentResponse]	true	none	A list of all currently active ConsentDocuments for the specified locale (`language`) and, if available, the associated UserConsents for the specified user. When the user only has a UserConsent with status `agreed` for a valid ConsentDocument (i.e. not for the active document), this ConsentDocument is also returned.

ActiveAttributesListResponse

{
  "attributes": [
    {
      "name": "consent-definition-name",
      "version": "v1.0",
      "attribute": {
        "legalBasis": "Consent",
        "version": "docVersion",
        "language": "EN",
        "effectiveDate": "2019-12-21T10:00:00.000Z",
        "processingPurpose": "I consent to the processing of my email address and first name in order to receive the daily newsletter.",
        "listOfAttributes": [
          "attr1",
          "attr2"
        ],
        "displayName": "Example attribute document"
      },
      "userConsent": {
        "id": "consent|consent-definition-name|v1.0::docVersion|EN",
        "userId": "user",
        "status": "agreed",
        "created": "2024-01-31T00:00:00+00:00",
        "lastUpdate": "2024-02-28T00:00:00+00:00",
        "client": "client-name"
      }
    }
  ]
}

Name	Type	Required	Restrictions	Description
attributes	[ActiveAttributeConsentResponse]	true	none	A list of all currently active AttributeConsentDocuments for the specified locale (`language`) and, if available, the associated UserConsents for the specified user. When the user only has a UserConsent with status `agreed` for a valid AttributeConsentDocument (i.e. not for the active document), this AttributeConsentDocument is also returned.

RegisterConsentRequestDocument

{
  "language": "EN",
  "version": "docVersion"
}

Name	Type	Required	Restrictions	Description
language	string	true	none	The `language` identifier for the (Attribute)ConsentDocument.
version	string	true	none	The `version` identifier for the (Attribute)ConsentDocument.

To

{
  "emailTo": "test@example.com"
}

Name	Type	Required	Restrictions	Description
emailTo	string	false	none	none

Parameters

{}

None

Message

{
  "parameters": {}
}

Name	Type	Required	Restrictions	Description
parameters	Parameters	false	none	none

RegisterConsentRequestConfirmationMessage

{
  "channel": "EMAIL",
  "to": {
    "emailTo": "test@example.com"
  },
  "message": {
    "parameters": {}
  }
}

Name	Type	Required	Restrictions	Description
channel	string	false	none	The communication channel, restricted to EMAIL for now.
to	To	false	none	The recipient details.
message	Message	false	none	The message details including template and any parameters.

Enumerated Values

Property	Value
channel	EMAIL

RegisterConsentRequest

{
  "name": "consent-definition-name",
  "version": "v1.0",
  "status": "agreed",
  "document": {
    "language": "EN",
    "version": "docVersion"
  },
  "confirmationMessage": {
    "channel": "EMAIL",
    "to": {
      "emailTo": "test@example.com"
    },
    "message": {
      "parameters": {}
    }
  }
}

Name	Type	Required	Restrictions	Description
name	string	true	none	The identifier for the (Attribute)ConsentDefinition.
version	string	true	none	The identifier for the (Attribute)ConsentVersion.
status	string	false	none	The status of the consent, i.e. whether the invitation to agree to the ConsentDocument has been agreed/rejected or is still pending.
document	RegisterConsentRequestDocument	true	none	The identifiers for the (Attribute)ConsentDocument.
confirmationMessage	RegisterConsentRequestConfirmationMessage	false	none	The configuration for the double opt-in message

Enumerated Values

Property	Value
status	agreed
status	pending
status	rejected

UserConsentResponse

{
  "id": "consent|consent-definition-name|v1.0::docVersion|EN",
  "userId": "user",
  "consent": {
    "name": "consent-definition-name",
    "version": "v1.0",
    "document": {
      "version": "docVersion",
      "language": "EN"
    },
    "gracePeriodEnds": "2024-01-31T00:00:00+00:00"
  }
}

Name	Type	Required	Restrictions	Description
id	string	true	none	An identifier for the UserConsent.
userId	string	true	none	An identifier for the User to whom the UserConsent applies.
consent	ConsentResponseWithoutStatus	true	none	The properties of the Consent.

DeleteConsentQueryParams

{
  "id": "consent|consent-definition-name|v1.0::docVersion|EN",
  "delete": false
}

Name	Type	Required	Restrictions	Description
id	string	true	none	The identifier for the UserConsent. The `id` can be found via one of the "List UserConsents" endpoints.
delete	boolean	false	none	A boolean indicating whether to remove (hard delete) the UserConsent object. By default, `delete:false`.

ProcessRequestTokenRequest

{
  "requestToken": "exampleRequestToken"
}

Name	Type	Required	Restrictions	Description
requestToken	string	true	none	A token that was generated via a "Register UserConsent" request for a consent that requires the double opt-in method.

RequestTokenResponse

{
  "requestToken": "exampleRequestToken"
}

Name	Type	Required	Restrictions	Description
requestToken	string	true	none	A request token to confirm or reject the registration of a UserConsent via the double opt-in method.

ConsentDefinition

{
  "name": "consent-definition-name",
  "displayName": "Example consent definition",
  "versionsCount": 1,
  "mandatory": true,
  "description": "Example ConsentDefinition description"
}

Name	Type	Required	Restrictions	Description
name	string	true	none	The identifier for the ConsentDefinition.
displayName	string	false	none	The human-readable name for the ConsentDefinition.
versionsCount	number	false	none	The amount of versions this ConsentDefinition has.
mandatory	boolean	true	none	Indicates whether the ConsentDefinition is mandatory.
description	string	false	none	A description for the ConsentDefinition.

ConsentDefinitionsResponse

{
  "links": {
    "resource1": "https://...",
    "resource2": "https://..."
  },
  "resources": [
    "consent-definition-name"
  ],
  "config": [
    {
      "name": "consent-definition-name",
      "displayName": "Example consent definition",
      "versionsCount": 1,
      "mandatory": true,
      "description": "Example ConsentDefinition description"
    }
  ],
  "cursor": "?cursor=..."
}

Name	Type	Required	Restrictions	Description
links	object	true	none	The URI's of the linked resources.
» additionalProperties	string	false	none	none
resources	[string]	true	none	A list with the `definitionName` of all ConsentDefinitions defined by the tenant.
config	[ConsentDefinition]	false	none	A list of all ConsentDefinitions defined by the tenant, including their properties. This information is only returned when `details=true` is included in the querystring of the request.
cursor	string	false	none	The last object to be evaluated by the current query. Pass it to the `cursor` query parameter of the next request to retrieve the next batch of items. If the response does not contain a value for `cursor`, then there are no additional results to retrieve.

AttributeConsentDefinitionResponse

{
  "links": {
    "resource1": "https://...",
    "resource2": "https://..."
  },
  "resources": [
    "versions"
  ],
  "config": {
    "name": "consent-definition-name",
    "displayName": "Example consent definition",
    "versionsCount": 1,
    "mandatory": true,
    "description": "Example ConsentDefinition description"
  }
}

Name	Type	Required	Restrictions	Description
links	object	true	none	The URI's of the linked resources.
» additionalProperties	string	false	none	none
resources	[string]	true	none	A list with the `version` of all ConsentVersions belonging to the ConsentDefinition.
config	ConsentDefinition	false	none	The properties of the ConsentDefinition.

AttributeConsentDefinitionRequest

{
  "description": "Example ConsentDefinition description",
  "displayName": "Example consent definition"
}

Name	Type	Required	Restrictions	Description
description	string	false	none	A description for the ConsentDefinition.
displayName	string	false	none	A human-readable name for the ConsentDefinition.

ConsentVersion

{
  "version": "v1.0",
  "displayName": "v1.0",
  "endOfLife": {
    "startDate": "2024-01-31T00:00:00+00:00",
    "endDate": "2024-12-31T00:00:00+00:00",
    "gracePeriod": "P0Y3M0D"
  },
  "optInConfig": [
    {
      "type": "direct"
    }
  ],
  "documentsCount": 1,
  "description": "Example ConsentVersion description"
}

Name	Type	Required	Restrictions	Description
version	string	true	none	The identifier for the ConsentVersion.
displayName	string	false	none	The human-readable name for the ConsentVersion.
endOfLife	EndOfLifeRequest	false	none	The endOfLife object which manages the termination of the ConsentVersion.
optInConfig	[OptInConfig]	true	none	The opt-in configuration for the ConsentVersion.
documentsCount	number	true	none	The amount of ConsentDocuments the ConsentVersion contains.
description	string	false	none	A description for the ConsentVersion.

ConsentVersionsResponse

{
  "links": {
    "resource1": "https://...",
    "resource2": "https://..."
  },
  "resources": [
    "versions"
  ],
  "config": [
    {
      "version": "v1.0",
      "displayName": "v1.0",
      "endOfLife": {
        "startDate": "2024-01-31T00:00:00+00:00",
        "endDate": "2024-12-31T00:00:00+00:00",
        "gracePeriod": "P0Y3M0D"
      },
      "optInConfig": [
        {
          "type": "direct"
        }
      ],
      "documentsCount": 1,
      "description": "Example ConsentVersion description"
    }
  ],
  "cursor": "?cursor=..."
}

Name	Type	Required	Restrictions	Description
links	object	true	none	The URI's of the linked resources.
» additionalProperties	string	false	none	none
resources	[string]	true	none	A list with the `version` of all ConsentVersions belonging to the requested ConsentDefinition.
config	[ConsentVersion]	false	none	A list of all ConsentVersions belonging to the requested ConsentDefinition, including their properties. This information is only returned when `details=true` is included in the querystring of the request.
cursor	string	false	none	The last object to be evaluated by the current query. Pass it to the `cursor` query parameter of the next request to retrieve the next batch of items. If the response does not contain a value for `cursor`, then there are no additional results to retrieve.

ConsentVersionResponse

{
  "links": {
    "resource1": "https://...",
    "resource2": "https://..."
  },
  "resources": [
    "documents",
    "end-of-life"
  ],
  "config": {
    "version": "v1.0",
    "displayName": "v1.0",
    "endOfLife": {
      "startDate": "2024-01-31T00:00:00+00:00",
      "endDate": "2024-12-31T00:00:00+00:00",
      "gracePeriod": "P0Y3M0D"
    },
    "optInConfig": [
      {
        "type": "direct"
      }
    ],
    "documentsCount": 1,
    "description": "Example ConsentVersion description"
  }
}

Name	Type	Required	Restrictions	Description
links	object	true	none	The URI's of the linked resources.
» additionalProperties	string	false	none	none
resources	[string]	true	none	A list of all child resources currently existing in this endpoint.
config	ConsentVersion	false	none	The object describing the requested config.

RequestTokenConfigRequest

{
  "expiresIn": "P0Y0M7D"
}

Name	Type	Required	Restrictions	Description
expiresIn	string	true	none	A duration (ISO 8601 Duration format) indicating the period the double-opt-in token is valid for. This period starts the moment the token is created.

MessageConfigRequest

{
  "channel": "EMAIL",
  "template": "double-opt-in",
  "emailSubjectLocaleKey": "email-subject.example-key"
}

Name	Type	Required	Restrictions	Description
channel	string	true	none	The channel name; currently, the only possible value is "EMAIL". In the future, "SMS" could be added.
template	string	true	none	The name of the message template configured in the tenant's ERS.
emailSubjectLocaleKey	string	true	none	The name of the message key in locale files to be used for the email subject

Enumerated Values

Property	Value
channel	EMAIL

OptInConfigRequest

{
  "type": "double",
  "requestTokenConfig": {
    "expiresIn": "P0Y0M7D"
  },
  "messageConfig": {
    "channel": "EMAIL",
    "template": "double-opt-in",
    "emailSubjectLocaleKey": "email-subject.example-key"
  }
}

Name	Type	Required	Restrictions	Description
type	string	true	none	The opt-in method applicable to the ConsentVersion.
requestTokenConfig	RequestTokenConfigRequest	true	none	none
messageConfig	MessageConfigRequest	true	none	none

Enumerated Values

Property	Value
type	direct
type	double

ConsentVersionRequest

{
  "optInConfig": [
    {
      "type": "double",
      "requestTokenConfig": {
        "expiresIn": "P0Y0M7D"
      },
      "messageConfig": {
        "channel": "EMAIL",
        "template": "double-opt-in",
        "emailSubjectLocaleKey": "email-subject.example-key"
      }
    }
  ],
  "description": "Example ConsentVersion description",
  "displayName": "v1.0"
}

Name	Type	Required	Restrictions	Description
optInConfig	[OptInConfigRequest]	true	none	The opt-in configuration for the ConsentVersion.
description	string	false	none	A description for the ConsentVersion.
displayName	string	false	none	A human-readable name for the ConsentVersion.

ConsentVersionEndOfLifeResponse

{
  "links": {
    "resource1": "https://...",
    "resource2": "https://..."
  },
  "config": {
    "startDate": "2024-01-31T00:00:00+00:00",
    "endDate": "2024-12-31T00:00:00+00:00",
    "gracePeriod": "P0Y3M0D"
  }
}

Name	Type	Required	Restrictions	Description
links	object	true	none	The URI's of the linked resources.
» additionalProperties	string	false	none	none
config	EndOfLifeRequest	false	none	The properties of the endOfLife object.

ListAttributeConsentQueryParams

{
  "details": false,
  "cursor": "?cursor=%7B%22tenant%22:%22onewelcome_e2e%22,%22id%22:%22consent-definition::a5df59d2-5da7-4263-a73d-0a55f6716267%22,%22type%22:%22consent-definition%22%7D",
  "limit": 1500,
  "title": "Example attribute document",
  "language": "EN",
  "legalBasis": "Consent",
  "attributes": "attr1,attr2",
  "status": "draft",
  "effectiveDate": "2026-01-26T16:00:00"
}

Name	Type	Required	Restrictions	Description
details	boolean	false	none	Indicates whether the complete `config` of the requested objects is included in the response.
cursor	object	false	none	uriEncoded JSON representation of the `cursor` object from the previous response.
limit	number	false	none	The maximum number of items returned in one response. When additional items are available, the response contains a `cursor` to request the next batch of items. By default, 100.
title	string	false	none	Filter for the `displayName` of the AttributeConsentDocument. The filtering is case-insensitive and accepts partial matches.
language	string	false	none	Filter for the locale (`language`) of the AttributeConsentDocument.
legalBasis	string	false	none	Filter for the `legalBasis` of the AttributeConsentDocument.
attributes	string	false	none	Filter for the `listOfAttributes` of the AttributeConsentDocument. Provide a comma-separated list. Only AttributeConsentDocuments that match all given attributes are returned.
status	string	false	none	Filter for the `status` of the AttributeConsentDocument.
effectiveDate	string	false	none	Filter for the effectiveDate of the AttributeConsentDocument. Returns all documents with an effectiveDate before the provided dateTime (ISO 8601 format in UTC).

Enumerated Values

Property	Value
legalBasis	Consent
legalBasis	Contract
legalBasis	Legal obligation
legalBasis	Legitimate interest
legalBasis	Public task
legalBasis	Vital interest
status	draft
status	active

AttributeDocument

{
  "legalBasis": "Consent",
  "version": "docVersion",
  "language": "EN",
  "status": "draft",
  "displayName": "Example attribute document",
  "effectiveDate": "2019-12-21T10:00:00.000Z",
  "processingPurpose": "I consent to the processing of my email address and first name in order to receive the daily newsletter.",
  "listOfAttributes": [
    "attr1",
    "attr2"
  ]
}

Name	Type	Required	Restrictions	Description
legalBasis	string	true	none	The legal basis for processing the specified personal data, i.e. one of the situations described in Article 6 of the General Data Protection Regulation (GDPR) guidelines.
version	string	true	none	An identifier for the AttributeConsentDocument. The AttributeConsentDocument is uniquely identified within the context of the AttributesConsentVersion by the combination of its `language` and `version`.
language	string	true	none	The locale for which the ConsentDocument applies, e.g. a language code and country/region code. Each AttributeConsentDocument only has one `language`.
status	string	true	none	The status of the AttributeConsentDocument.
displayName	string	false	none	The human-readable name for the AttributeConsentDocument.
effectiveDate	string	false	none	A datetime (ISO 8601 format) indicating the moment in time at which the AttributeConsentDocument can become effective and might replace a previous version.
processingPurpose	string	true	none	A short text for the end user, written in the language specified in the locale `language`, stating what personal data is processed for what purpose.
listOfAttributes	[string]	true	none	The types of personal data that are processed when the user consents to the AttributeConsentDocument.

Enumerated Values

Property	Value
legalBasis	Consent
legalBasis	Contract
legalBasis	Legal obligation
legalBasis	Legitimate interest
legalBasis	Public task
legalBasis	Vital interest
status	draft
status	active

AttributeConsentDocumentsResponse

{
  "links": {
    "resource1": "https://...",
    "resource2": "https://..."
  },
  "resources": [
    "versions"
  ],
  "config": [
    {
      "legalBasis": "Consent",
      "version": "docVersion",
      "language": "EN",
      "status": "draft",
      "displayName": "Example attribute document",
      "effectiveDate": "2019-12-21T10:00:00.000Z",
      "processingPurpose": "I consent to the processing of my email address and first name in order to receive the daily newsletter.",
      "listOfAttributes": [
        "attr1",
        "attr2"
      ]
    }
  ],
  "cursor": "?cursor=..."
}

Name	Type	Required	Restrictions	Description
links	object	true	none	The URI's of the linked resources.
» additionalProperties	string	false	none	none
resources	[string]	true	none	A list with the `version` of each requested AttributeConsentDocument.
config	[AttributeDocument]	false	none	A list of all requested AttributeConsentDocuments, including their properties. This information is only returned when `details=true` is included in the querystring of the request.
cursor	string	false	none	The last object to be evaluated by the current query. Pass it to the `cursor` query parameter of the next request to retrieve the next batch of items. If the response does not contain a value for `cursor`, then there are no additional results to retrieve.

AttributeConsentDocumentResponse

{
  "links": {
    "resource1": "https://...",
    "resource2": "https://..."
  },
  "config": {
    "legalBasis": "Consent",
    "version": "docVersion",
    "language": "EN",
    "status": "draft",
    "displayName": "Example attribute document",
    "effectiveDate": "2019-12-21T10:00:00.000Z",
    "processingPurpose": "I consent to the processing of my email address and first name in order to receive the daily newsletter.",
    "listOfAttributes": [
      "attr1",
      "attr2"
    ]
  }
}

Name	Type	Required	Restrictions	Description
links	object	true	none	The URI's of the linked resources.
» additionalProperties	string	false	none	none
config	AttributeDocument	false	none	The properties of the AttributeConsentDocument.

AttributeConsentDocumentRequest

{
  "effectiveDate": "2024-01-31T00:00:00+00:00",
  "status": "active",
  "displayName": "Example attribute document",
  "processingPurpose": "I consent to the processing of my email address and first name in order to receive the daily newsletter.",
  "listOfAttributes": [
    "attr1",
    "attr2"
  ],
  "legalBasis": "Consent"
}

Name	Type	Required	Restrictions	Description
effectiveDate	string	false	none	A datetime (ISO 8601 format) indicating the moment in time at which this specific ConsentDocument can become effective and might replace a previous version. The `effectivedate` cannot be set in the past. When a ConsentDocument is created with `status=active`, the effectiveDate is set to the current timestamp by default.
status	string	false	none	The status of the ConsentDocument.
displayName	string	false	none	The human-readable name of the ConsentDocument.
processingPurpose	string	false	none	A short text for the end user, written in the language specified in the locale `language`, stating what personal data is processed for what purpose.
listOfAttributes	[string]	true	none	The type(s) of personal data that is processed when the user consents to the AttributeConsentDocument. The string should match the identifier for the attribute in your profile store.
legalBasis	string	true	none	The legal basis for processing the specified personal data, i.e. one of the situations described in Article 6 of the General Data Protection Regulation (GDPR) guidelines (gdpr-info.eu/art-6-gdpr).

Enumerated Values

Property	Value
status	draft
status	active
legalBasis	Consent
legalBasis	Contract
legalBasis	Legal obligation
legalBasis	Legitimate interest
legalBasis	Public task
legalBasis	Vital interest

ConsentDefinitionResponse

{
  "links": {
    "resource1": "https://...",
    "resource2": "https://..."
  },
  "resources": [
    "versions"
  ],
  "config": {
    "name": "consent-definition-name",
    "displayName": "Example consent definition",
    "versionsCount": 1,
    "mandatory": true,
    "description": "Example ConsentDefinition description"
  }
}

Name	Type	Required	Restrictions	Description
links	object	true	none	The URI's of the linked resources.
» additionalProperties	string	false	none	none
resources	[string]	true	none	A list with the `version` of all ConsentVersions belonging to the ConsentDefinition.
config	ConsentDefinition	false	none	The properties of the ConsentDefinition.

ConsentDefinitionRequest

{
  "mandatory": false,
  "description": "Example ConsentDefinition description",
  "displayName": "Example consent definition"
}

Name	Type	Required	Restrictions	Description
mandatory	boolean	false	none	Indicates whether the ConsentDefinition is mandatory.
description	string	false	none	A description for the ConsentDefinition.
displayName	string	false	none	A human-readable name for the ConsentDefinition.

ConsentDocumentsLanguagesResponse

{
  "links": {
    "resource1": "https://...",
    "resource2": "https://..."
  },
  "config": {
    "EN": [
      {
        "version": "docVersionX",
        "displayName": "displayName docVersionX",
        "language": "EN",
        "effectiveDate": "2024-05-10T03:01:44.162Z",
        "url": "https://{host}/termsandconditions.com",
        "status": "active",
        "eolStatus": "valid",
        "description": "description docVersionX"
      }
    ]
  },
  "resources": [
    "EN"
  ]
}

Name	Type	Required	Restrictions	Description
links	object	true	none	The URI's of the linked resources.
» additionalProperties	string	false	none	none
config	object	false	none	A map where the key is a language code and the value is an array of ConsentDocuments belonging to the requested ConsentVersion, including their properties. This information is only returned when `details=true` is included in the query string of the request.
» additionalProperties	[ConsentDocument]	false	none	none
resources	[string]	true	none	A list of the languages (`language`) for which ConsentDocuments exist in the requested ConsentVersion.

ConsentDocumentsResponse

{
  "links": {
    "resource1": "https://...",
    "resource2": "https://..."
  },
  "resources": [
    "versions"
  ],
  "config": [
    {
      "version": "docVersion",
      "displayName": "Example document",
      "language": "EN",
      "effectiveDate": "2019-12-21T10:00:00.000Z",
      "url": "https://www.example.com/documentContent",
      "status": "draft",
      "description": "Example ConsentDocument description",
      "eolStatus": "scheduled"
    }
  ],
  "cursor": "?cursor=..."
}

Name	Type	Required	Restrictions	Description
links	object	true	none	The URI's of the linked resources.
» additionalProperties	string	false	none	none
resources	[string]	true	none	A list with the `version` of each requested ConsentDocument.
config	[ConsentDocument]	false	none	A list of all requested ConsentDocuments, including their properties. This information is only returned when `details=true` is included in the querystring of the request.
cursor	string	false	none	The last object to be evaluated by the current query. Pass it to the `cursor` query parameter of the next request to retrieve the next batch of items. If the response does not contain a value for `cursor`, then there are no additional results to retrieve.

ConsentDocumentResponse

{
  "links": {
    "resource1": "https://...",
    "resource2": "https://..."
  },
  "config": {
    "version": "docVersion",
    "displayName": "Example document",
    "language": "EN",
    "effectiveDate": "2019-12-21T10:00:00.000Z",
    "url": "https://www.example.com/documentContent",
    "status": "draft",
    "description": "Example ConsentDocument description",
    "eolStatus": "scheduled"
  }
}

Name	Type	Required	Restrictions	Description
links	object	true	none	The URI's of the linked resources.
» additionalProperties	string	false	none	none
config	ConsentDocument	false	none	The properties of the ConsentDocument.

ConsentDocumentRequest

{
  "effectiveDate": "2024-01-31T00:00:00+00:00",
  "status": "active",
  "description": "Example ConsentDocument description",
  "url": "https://www.example.com/documentContent",
  "displayName": "Example document"
}

Name	Type	Required	Restrictions	Description
effectiveDate	string	false	none	A datetime (ISO 8601 format) indicating the moment in time at which this specific ConsentDocument can become effective and might replace a previous version. The `effectiveDate` cannot be set in the past. When a ConsentDocument is created with `status=active`, the effectiveDate is set to the current timestamp by default.
status	string	false	none	The status of the ConsentDocument.
description	string	false	none	A description for the ConsentDocument.
url	string	false	none	A URL which can be used to share the content of the ConsentDocument with the user.
displayName	string	false	none	The human-readable name of the ConsentDocument.

Enumerated Values

Property	Value
status	draft
status	active

Relationship-based Access Control

The OneWelcome Relationship-based Access Control feature enables the customer to set up a system of delegated administration with which users can self-manage their relationships to digital assets.

Overview and Concepts

About Relationship-based Access Control

Relationships are the basic unit that link users and assets into a network. This network can be represented in a graph as a collection of "nodes" and "edges". Each node is a digital representation of one user or asset and each edge represents a relationship between the two adjacent nodes. These relationships can by nature be bi-directional, e.g. John and Jane are siblings, or uni-directional, e.g. John is the owner of Buddy, a dog. Therefore, a direction is defined for each of the relationships in the system.

Examples

Assets	Relationships
an appliance a device a subscription a confidential report a pet an IoT device	"User X `is_owner_of` pet A." "User X `is_admin_of` and user Y `is_member_of` subscription B. " "User X `is_sibling_of` user Y and vice versa."

When users share an asset in real-life (i.e. they "have a relationship" with the asset), they can also share its corresponding digital resource. The resulting digital network can then be used to:

determine which access rights a user has for the digital resources related to these real-life assets, and
connect people (e.g. a smart lock owner can be connected with professionals such as the vendor, technicians, and the alarm center).

Relationship-based Access Control with OneWelcome

Creating and maintaining this type of network can be done centrally by the customer's back office or can be self-managed by the users in the network. The latter ensures a fast and scalable system to manage relationships (and thus the access to protected resources). OneWelcome offers help with this so-called Relationship-based Access Control by providing an API-based system to:

Config API: Define and customize types of actors, resources, and relationships.
Relationship Management API: Create and manage actors, resources, and relationships.
Authorization API: Take relationships into account to make authorization decisions.

Configuration of the Domain Model: Config API

Information Model

The Config API enables OneWelcome customers, called tenants, to define a domain model with ActorTypes, ResourceTypes, and RelationshipTypes. These attributes of Actors, Resources, or Relationships are used by the Relationship Management API to:

grant the associated Actors specific access rights (see Authorization API),
determine whether a type of relationship is allowed between two objects, and
define custom attributes.

The ActorType user is already defined for new tenants. The properties attribute can be specified via Create/update an ActorType.

Objects and Attributes

RelationshipType restrictions

Code example A: RelationshipType is_sibling_of

"restrictions":  [
  { "from": "user"; "to": "user" }
]

Code example B: RelationshipType is_owner_of

"restrictions":  [
  { "from": "user"; "to": "pet" }
  { "from": "user"; "to": "smart_lock" }
]

The restrictions object specifies a list of allowed ActorType/ResourceType combinations with a defined direction (from/to). When relationships are assigned with the Relationship Management API, these restrictions are taken into account for the requested RelationshipType.

Custom attributes

The properties attribute of the ActorTypes, ResourceTypes, and RelationshipTypes can be used to define additional (required or optional) attributes specific for the subset of objects. For example, the ResourceType pet can have the custom attributes external_identifier, birthdate, and chip_number.

Access token Authorization

Requests sent to the Relationship Management API must be accompanied by an access token issued by a trusted authorization server. To validate the token, the issuer and its JWKS endpoint must be known to OneWelcome. Optionally, the tenant can define an audience which must be specified in the access token.

To view or update the configuration for the Relationship Management API, use the following endpoints:

Get authorization config
Update authorization config

Integration of access token claims

User requests sent to the Relationship Management API must be accompanied by an access token which contains claims for the Actor attributes actorId and actorType (see Managing of Relationships). To guarantee the correct integration of your access tokens with OneWelcome, you might need to specify the correct (custom) claims for these attributes.

New tenants are set up as follows:

actorIdClaimPath: "$.sub"
actorTypeClaimPath: "$.['https://your.namespace.com/node-type']"

To view or update the TokenMapping for your tenant, use the following endpoints:

Get TokenMapping
Update TokenMapping

When the TokenMapping configuration is absent or invalid, the UserId is set to the value of the sub claim and the UserType is set to the default ActorType user.

Managing of Relationships: Relationship Management API

Information Model

The Relationship Management API handles the actual creation and managing of Actors (such as Users), Resources, and Relationships. Actors can self-manage their Resources and Relationships and can invite other Actors to have a Relationship with one of their Resources.

Objects and Attributes

Invitations

Actors (or a back-office) can send invitations to other actors to propose a Relationship with one of their Resources or another Actor. In the relationship network, an Invitation can have up to three Relationships. Upon its creation, it gets a Relationship with the inviting Actor (isCreatedBy) and with the Actor or Resource for which a Relationship is proposed (targets). When the invitee accepts the invitation, a third Relationship is formed with the Actor object of the invitee (isAcceptedBy). Alternatively, the invitor might want to revoke the invitation, which results in an additional Relationship between the Invitation and that Actor (isRevokedBy). An invitation can no longer be revoked when it has been accepted. Therefore, there will never be an isAcceptedBy and isRevokedBy for the same Invitation.

Authorization

The policies specified for the Relationship Management API determine which actions actors can take on which objects. This can be based on attributes of the involved Actors, Resources, Relationships, and Invitations such as the type and relationship direction (from or to). These policies can be specified by the tenant admin (see Configuration of Policies).

New tenants are set up according to a blueprint specifying default policies for use of the Relationship Management API. These policies specify that:

Actors only have access to Resources to which they are directly related.
Actors have limited access to Actor objects with which they share a common Resource (e.g. a pet owner can request contact details of the vet treating the pet).
Actors can only create an Invitation for a Resource to which they are directly related.
An Invitation can only be withdrawn by the invitor.
An Invitation can only be withdrawn as long as it is not yet accepted.

Using Relationships in Authorization Decisions: Authorization API

Policies

To fully profit from the relationship network created with the Relationship Management API, the tenant can design policies for their application based on the attributes of Actors, Resources, and Relationships. See Externalized Authorization for more information on how to define and implement these policies for your application.

Endpoints Overview

Relationship Config API

Get TokenMapping

Code samples

# You can also use wget
curl -X GET /groups/token-mapping \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /groups/token-mapping HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/groups/token-mapping',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /groups/token-mapping

Returns the TokenMapping configuration.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter or no acting tenant
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {
    "actorIdClaimPath": "string",
    "actorTypeClaimPath": "string"
  },
  "cursor": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	none	TokenMappingResponse

Update TokenMapping

Code samples

# You can also use wget
curl -X PUT /groups/token-mapping \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

PUT /groups/token-mapping HTTP/1.1

Content-Type: application/json
Accept: application/json
acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "actorIdClaimPath": "string",
  "actorTypeClaimPath": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/groups/token-mapping',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /groups/token-mapping

Updates the TokenMapping configuration.

Body parameter

{
  "actorIdClaimPath": "string",
  "actorTypeClaimPath": "string"
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter or no acting tenant
tenant	path	string	true	Your tenant code.
body	body	SaveTokenMappingRequest	true	none

Example responses

200 Response

{}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Get Authorization Config

Code samples

# You can also use wget
curl -X GET /groups/authConfig \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /groups/authConfig HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/groups/authConfig',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /groups/authConfig

Returns the authorization configuration (JWKS and JWT details).

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter or no acting tenant
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {
    "jwksUri": "string",
    "issuer": "string",
    "audience": "string"
  },
  "cursor": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	none	AuthorizationConfigResponse

Update authorization config

Code samples

# You can also use wget
curl -X PUT /groups/authConfig \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

PUT /groups/authConfig HTTP/1.1

Content-Type: application/json
Accept: application/json
acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "jwksUri": "string",
  "issuer": "string",
  "audience": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/groups/authConfig',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /groups/authConfig

Updates the authorization configuration (JWKS and JWT details)

Body parameter

{
  "jwksUri": "string",
  "issuer": "string",
  "audience": "string"
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter or no acting tenant
tenant	path	string	true	Your tenant code.
body	body	AuthorizationConfigRequest	true	none

Example responses

200 Response

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {
    "jwksUri": "string",
    "issuer": "string",
    "audience": "string"
  },
  "cursor": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	none	AuthorizationConfigResponse

Get Webhook configuration

Code samples

# You can also use wget
curl -X GET /groups/hooks/{provider} \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /groups/hooks/{provider} HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/groups/hooks/{provider}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /groups/hooks/{provider}

Returns the Webhook configuration for a given provider.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter or no acting tenant
provider	path	string	true	none
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {},
  "cursor": "string",
  "providerConfig": {
    "apiKey": "string"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	HookProviderConfigResponse

Setup WebHook Configuration

Code samples

# You can also use wget
curl -X POST /groups/hooks/{provider} \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /groups/hooks/{provider} HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/groups/hooks/{provider}',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /groups/hooks/{provider}

Set up the WebHook configuration for a given provider.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter or no acting tenant
provider	path	string	true	none
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

> RelationshipType Endpoints

List all RelationshipTypes

Code samples

# You can also use wget
curl -X GET /groups/relationship-types \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /groups/relationship-types HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/groups/relationship-types',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /groups/relationship-types

Lists all defined RelationshipTypes.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter or no acting tenant
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {},
  "cursor": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	none	RelationshipTypeListResponse

Get a RelationshipType

Code samples

# You can also use wget
curl -X GET /groups/relationship-types/{relationshipType} \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /groups/relationship-types/{relationshipType} HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/groups/relationship-types/{relationshipType}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /groups/relationship-types/{relationshipType}

Returns a specific RelationshipType.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter or no acting tenant
relationshipType	path	string	true	The type of Relationship.
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {
    "name": "string",
    "description": "string",
    "restrictions": [
      {
        "from": "string",
        "to": "string"
      }
    ],
    "properties": [
      {
        "name": "isActive",
        "type": "boolean"
      }
    ]
  },
  "cursor": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	none	RelationshipTypeResponse

Create/update a RelationshipType

Code samples

# You can also use wget
curl -X PUT /groups/relationship-types/{relationshipType} \
  -H 'Content-Type: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

PUT /groups/relationship-types/{relationshipType} HTTP/1.1

Content-Type: application/json

acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "description": "string",
  "restrictions": [
    {
      "from": "string",
      "to": "string"
    }
  ],
  "properties": [
    {}
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/groups/relationship-types/{relationshipType}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /groups/relationship-types/{relationshipType}

Creates or updates a RelationshipType. In addition, if the from type is an Actor, a default Policy of type {fromType}:{relationshipType}:{toType}:read is created, unless it already exists.

Note: A PUT request overwrites the original object. Be sure to (re-)enter the values for all desired properties.

Body parameter

{
  "description": "string",
  "restrictions": [
    {
      "from": "string",
      "to": "string"
    }
  ],
  "properties": [
    {}
  ]
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter or no acting tenant
relationshipType	path	string	true	The type of Relationship.
tenant	path	string	true	Your tenant code.
body	body	SaveRelationshipTypeRequest	true	none

Responses

Status	Meaning	Description	Schema
200	OK	none	None

Delete RelationshipType

Code samples

# You can also use wget
curl -X DELETE /groups/relationship-types/{relationshipType} \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

DELETE /groups/relationship-types/{relationshipType} HTTP/1.1

acting-tenant-id: string
tenant-id: string


const headers = {
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/groups/relationship-types/{relationshipType}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /groups/relationship-types/{relationshipType}

Removes the specified RelationshipType.

Note: Data with this RelationshipType will NOT be erased.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter or no acting tenant
relationshipType	path	string	true	none
to	query	array	true	An ordered list of "to" restrictions that specify which restriction needs to be deleted.
from	query	array	true	An ordered list of "from" restrictions that specify which restriction needs to be deleted.

Detailed descriptions

to: An ordered list of "to" restrictions that specify which restriction needs to be deleted. The to value for each position combines with the from value in the same position to create a restriction.

e.g. ?from=a,b&to=c,d results in two restrictions being deleted: {from: "a", to: "c"} and {from: "b", to: "d"}

from: An ordered list of "from" restrictions that specify which restriction needs to be deleted. The from value for each position combines with the to value in the same position to create a restriction.

e.g. ?from=a,b&to=c,d results in two restrictions being deleted: {from: "a", to: "c"} and {from: "b", to: "d"}

Responses

Status	Meaning	Description	Schema
204	No Content	none	None

> ResourceType Endpoints

List all ResourceTypes

Code samples

# You can also use wget
curl -X GET /groups/resources \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /groups/resources HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/groups/resources',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /groups/resources

Lists all defined ResourceTypes.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter or no acting tenant
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {},
  "cursor": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ResourceTypeListResponse

Get a ResourceType

Code samples

# You can also use wget
curl -X GET /groups/resources/{resourceType} \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /groups/resources/{resourceType} HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/groups/resources/{resourceType}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /groups/resources/{resourceType}

Returns a specific ResourceType.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter or no acting tenant
resourceType	path	string	true	The type of Resource.
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {
    "name": "string",
    "description": "string",
    "properties": [
      {}
    ]
  },
  "cursor": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ResourceTypeResponse

Create/update a ResourceType

Code samples

# You can also use wget
curl -X PUT /groups/resources/{resourceType} \
  -H 'Content-Type: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

PUT /groups/resources/{resourceType} HTTP/1.1

Content-Type: application/json

acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "description": "string",
  "properties": [
    {}
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/groups/resources/{resourceType}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /groups/resources/{resourceType}

Creates or updates a ResourceType.

Note: A PUT request overwrites the original object. Be sure to (re-)enter the values for all desired properties.

Body parameter

{
  "description": "string",
  "properties": [
    {}
  ]
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter or no acting tenant
resourceType	path	string	true	The type of Resource.
tenant	path	string	true	Your tenant code.
body	body	SaveResourceTypeRequest	true	none

Responses

Status	Meaning	Description	Schema
200	OK	none	None

Delete ResourceType

Code samples

# You can also use wget
curl -X DELETE /groups/resources/{resourceType} \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

DELETE /groups/resources/{resourceType} HTTP/1.1

acting-tenant-id: string
tenant-id: string


const headers = {
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/groups/resources/{resourceType}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /groups/resources/{resourceType}

Removes the specified ResourceType.

Note: Data with this ResourceType will NOT be erased.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter or no acting tenant
resourceType	path	string	true	none

Responses

Status	Meaning	Description	Schema
204	No Content	none	None

> ActorType Endpoints

List all ActorTypes

Code samples

# You can also use wget
curl -X GET /groups/actors \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /groups/actors HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/groups/actors',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /groups/actors

Lists all defined ActorTypes.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter or no acting tenant
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {},
  "cursor": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ActorTypeListResponse

Get an ActorType

Code samples

# You can also use wget
curl -X GET /groups/actors/{actorType} \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /groups/actors/{actorType} HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/groups/actors/{actorType}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /groups/actors/{actorType}

Returns a specific ActorType.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter or no acting tenant
actorType	path	string	true	The type of Actor.
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {},
  "cursor": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ActorTypeResponse

Create/update an ActorType

Code samples

# You can also use wget
curl -X PUT /groups/actors/{actorType} \
  -H 'Content-Type: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

PUT /groups/actors/{actorType} HTTP/1.1

Content-Type: application/json

acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "description": "string",
  "properties": [
    {}
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/groups/actors/{actorType}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /groups/actors/{actorType}

Creates or updates an ActorType. In addition, a default Policy of type {actorType}:read is created, unless it already exists.

Note: A PUT request overwrites the original object. Be sure to (re-)enter the values for all desired properties.

Body parameter

{
  "description": "string",
  "properties": [
    {}
  ]
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter or no acting tenant
actorType	path	string	true	The type of Actor.
tenant	path	string	true	Your tenant code.
body	body	SaveActorTypeRequest	true	none

Responses

Status	Meaning	Description	Schema
200	OK	none	None

Delete ActorType

Code samples

# You can also use wget
curl -X DELETE /groups/actors/{actorType} \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

DELETE /groups/actors/{actorType} HTTP/1.1

acting-tenant-id: string
tenant-id: string


const headers = {
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/groups/actors/{actorType}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /groups/actors/{actorType}

Removes the specified ActorType.

Note: Data with this ActorType will NOT be erased.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter or no acting tenant
actorType	path	string	true	none

Responses

Status	Meaning	Description	Schema
204	No Content	none	None

> DomainModel Endpoints

Get domain model

Code samples

# You can also use wget
curl -X GET /groups/domain \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /groups/domain HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/groups/domain',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /groups/domain

Returns a the complete domain model.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter or no acting tenant
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "resourceTypes": [
    {
      "name": "string",
      "description": "string",
      "properties": [
        {}
      ]
    }
  ],
  "actorTypes": [
    {
      "name": "string",
      "description": "string",
      "properties": [
        {}
      ]
    }
  ],
  "relationshipTypes": [
    {
      "name": "string",
      "description": "string",
      "restrictions": [
        {
          "from": "string",
          "to": "string"
        }
      ],
      "properties": [
        {
          "name": "isActive",
          "type": "boolean"
        }
      ]
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	none	DomainModelResponse

Schemas

RelationshipTypeListResponse

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {},
  "cursor": "string"
}

Name	Type	Required	Restrictions	Description
resources	[string]	true	none	A list of the RelationshipTypes.
links	object	true	none	The URI's of the linked resources.
config	object	false	none	The object describing the requested config.
cursor	string	false	none	A cursor indicating the start of the next page of results.

Restriction

{
  "from": "string",
  "to": "string"
}

Name	Type	Required	Restrictions	Description
from	string	true	none	The ActorType or ResourceType from which the Relationship can start.
to	string	true	none	The ActorType or ResourceType at which the Relationship can end.

ElementTypeProperty

{}

None

RelationshipTypeConfig

{
  "name": "string",
  "description": "string",
  "restrictions": [
    {
      "from": "string",
      "to": "string"
    }
  ],
  "properties": [
    {
      "name": "isActive",
      "type": "boolean"
    }
  ]
}

Name	Type	Required	Restrictions	Description
name	string	true	none	The name of the RelationshipType.
description	string	false	none	A human-readable description for the RelationshipType.
restrictions	[Restriction]	true	none	none
properties	[ElementTypeProperty]	false	none	Custom attributes for the Relationship Type.

RelationshipTypeResponse

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {
    "name": "string",
    "description": "string",
    "restrictions": [
      {
        "from": "string",
        "to": "string"
      }
    ],
    "properties": [
      {
        "name": "isActive",
        "type": "boolean"
      }
    ]
  },
  "cursor": "string"
}

Name	Type	Required	Restrictions	Description
resources	[string]	true	none	A list of all child resources currently existing in this endpoint.
links	object	true	none	The URI's of the linked resources.
config	RelationshipTypeConfig	false	none	The object describing the requested config.
cursor	string	false	none	A cursor indicating the start of the next page of results.

SaveRelationshipTypeRequest

{
  "description": "string",
  "restrictions": [
    {
      "from": "string",
      "to": "string"
    }
  ],
  "properties": [
    {}
  ]
}

Name	Type	Required	Restrictions	Description
description	string	true	none	A human-readable description for the RelationshipType.
restrictions	[Restriction]	true	none	A list of allowed ActorType/ResourceType combinations with a defined direction (`from`/`to`). The chosen Types must already exist. At least 1 item is required.
properties	[ElementTypeProperty]	false	none	Custom properties of the RelationshipType.

TokenMapping

{
  "actorIdClaimPath": "string",
  "actorTypeClaimPath": "string"
}

Name	Type	Required	Restrictions	Description
actorIdClaimPath	string	true	none	The path to the claim in the access token which represents the `userId` of the authenticated User.
actorTypeClaimPath	string	true	none	The path to the claim in the access token which represents the `userType` of the authenticated User.

TokenMappingResponse

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {
    "actorIdClaimPath": "string",
    "actorTypeClaimPath": "string"
  },
  "cursor": "string"
}

Name	Type	Required	Restrictions	Description
resources	[string]	true	none	A list of all child resources currently existing in this endpoint.
links	object	true	none	The URI's of the linked resources.
config	TokenMapping	false	none	The object describing the requested config.
cursor	string	false	none	A cursor indicating the start of the next page of results.

SaveTokenMappingRequest

{
  "actorIdClaimPath": "string",
  "actorTypeClaimPath": "string"
}

Name	Type	Required	Restrictions	Description
actorIdClaimPath	string	true	none	The path to the claim in the access token which represents the `userId` of the authenticated User.
actorTypeClaimPath	string	true	none	The path to the claim in the access token which represents the `userType` of the authenticated User.

ResourceTypeListResponse

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {},
  "cursor": "string"
}

Name	Type	Required	Restrictions	Description
resources	[string]	true	none	A list of the ResourceTypes.
links	object	true	none	The URI's of the linked resources.
config	object	false	none	The object describing the requested config.
cursor	string	false	none	A cursor indicating the start of the next page of results.

ResourceTypeProperty

{}

None

ResourceTypeConfig

{
  "name": "string",
  "description": "string",
  "properties": [
    {}
  ]
}

Name	Type	Required	Restrictions	Description
name	string	true	none	The name of the ResourceType.
description	string	true	none	A human-readable description for the ResourceType.
properties	[ResourceTypeProperty]	false	none	Custom properties of the ResourceType.

ResourceTypeResponse

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {
    "name": "string",
    "description": "string",
    "properties": [
      {}
    ]
  },
  "cursor": "string"
}

Name	Type	Required	Restrictions	Description
resources	[string]	true	none	A list of all child resources currently existing in this endpoint.
links	object	true	none	The URI's of the linked resources.
config	ResourceTypeConfig	false	none	The object describing the requested config.
cursor	string	false	none	A cursor indicating the start of the next page of results.

SaveResourceTypeRequest

{
  "description": "string",
  "properties": [
    {}
  ]
}

Name	Type	Required	Restrictions	Description
description	string	true	none	A human-readable description for the ResourceType.
properties	[ResourceTypeProperty]	false	none	Custom properties of the ResourceType.

ActorTypeListResponse

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {},
  "cursor": "string"
}

Name	Type	Required	Restrictions	Description
resources	[string]	true	none	A list of all child resources currently existing in this endpoint.
links	object	true	none	The URI's of the linked resources.
config	object	false	none	The object describing the requested config.
cursor	string	false	none	A cursor indicating the start of the next page of results.

ActorTypeResponse

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {},
  "cursor": "string"
}

Name	Type	Required	Restrictions	Description
resources	[string]	true	none	A list of all child resources currently existing in this endpoint.
links	object	true	none	The URI's of the linked resources.
config	object	false	none	The object describing the requested config.
cursor	string	false	none	A cursor indicating the start of the next page of results.

SaveActorTypeRequest

{
  "description": "string",
  "properties": [
    {}
  ]
}

Name	Type	Required	Restrictions	Description
description	string	true	none	A human-readable description for the ActorType.
properties	[ElementTypeProperty]	false	none	Custom properties of the ActorType.

AuthorizationConfig

{
  "jwksUri": "string",
  "issuer": "string",
  "audience": "string"
}

Name	Type	Required	Restrictions	Description
jwksUri	string	true	none	The URI of the JSON Web Key Set.
issuer	string	true	none	The URI of the JWT issuer.
audience	string	false	none	The expected audience of the JWT.

AuthorizationConfigResponse

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {
    "jwksUri": "string",
    "issuer": "string",
    "audience": "string"
  },
  "cursor": "string"
}

Name	Type	Required	Restrictions	Description
resources	[string]	true	none	A list of all child resources currently existing in this endpoint.
links	object	true	none	The URI's of the linked resources.
config	AuthorizationConfig	false	none	The object describing the requested config.
cursor	string	false	none	A cursor indicating the start of the next page of results.

AuthorizationConfigRequest

{
  "jwksUri": "string",
  "issuer": "string",
  "audience": "string"
}

Name	Type	Required	Restrictions	Description
jwksUri	string	true	none	The URI of the JSON Web Key Set.
issuer	string	true	none	The URI of the JWT issuer.
audience	string	false	none	The expected audience of the JWT.

ActorTypeProperty

{}

None

ActorTypeConfig

{
  "name": "string",
  "description": "string",
  "properties": [
    {}
  ]
}

Name	Type	Required	Restrictions	Description
name	string	true	none	The name of the ActorType.
description	string	true	none	A human-readable description for the ActorType.
properties	[ActorTypeProperty]	false	none	Custom properties of the ActorType.

DomainModelResponse

{
  "resourceTypes": [
    {
      "name": "string",
      "description": "string",
      "properties": [
        {}
      ]
    }
  ],
  "actorTypes": [
    {
      "name": "string",
      "description": "string",
      "properties": [
        {}
      ]
    }
  ],
  "relationshipTypes": [
    {
      "name": "string",
      "description": "string",
      "restrictions": [
        {
          "from": "string",
          "to": "string"
        }
      ],
      "properties": [
        {
          "name": "isActive",
          "type": "boolean"
        }
      ]
    }
  ]
}

Name	Type	Required	Restrictions	Description
resourceTypes	[ResourceTypeConfig]	false	none	ResourceTypes
actorTypes	[ActorTypeConfig]	false	none	ActorTypes
relationshipTypes	[RelationshipTypeConfig]	false	none	RelationshipTypes

HookProviderConfig

{
  "apiKey": "string"
}

Name	Type	Required	Restrictions	Description
apiKey	string	true	none	The apiKey used for authorizing the provider's webhook

HookProviderConfigResponse

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {},
  "cursor": "string",
  "providerConfig": {
    "apiKey": "string"
  }
}

Name	Type	Required	Restrictions	Description
resources	[string]	true	none	A list of all child resources currently existing in this endpoint.
links	object	true	none	The URI's of the linked resources.
config	object	false	none	The object describing the requested config.
cursor	string	false	none	A cursor indicating the start of the next page of results.
providerConfig	HookProviderConfig	false	none	none

Relationship Management API

Get JSON Web Key Set

Code samples

# You can also use wget
curl -X GET /api/v1/.well-known/jwks.json \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string'

GET /api/v1/.well-known/jwks.json HTTP/1.1

acting-tenant-id: string
tenant-id: string


const headers = {
  'acting-tenant-id':'string',
  'tenant-id':'string'
};

fetch('/api/v1/.well-known/jwks.json',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/.well-known/jwks.json

Returns an array of JSON Web Keys as defined by the JSON Web Key (JWK) specification. This can be used to verify the tokens this service has signed.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
tenant	path	string	true	Your tenant code.

Responses

Status	Meaning	Description	Schema
200	OK	none	None

> My Actor Endpoints

Get my Actor

Code samples

# You can also use wget
curl -X GET /api/v1/actors/me \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/actors/me HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/actors/me',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/actors/me

Returns the Actor authenticated by the user access token.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "id": "string",
  "type": "string",
  "customAttribute1": "string",
  "customAttribute2": "boolean"
}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» id	string	true	none	The identifier of the Actor.
» type	string	true	none	The type of the Actor.
» customAttribute	any	false	none	A property defined by the tenant for this type of object.

Authorization request template

{
  "action": "${principal.nodeType}:read",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}"
  }
}

Authorization Request

Create/update my Actor

Code samples

# You can also use wget
curl -X PUT /api/v1/actors/me \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

PUT /api/v1/actors/me HTTP/1.1

Content-Type: application/json
Accept: application/json
acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "customAttribute1": "value1",
  "customAttribute2": "value2"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/actors/me',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /api/v1/actors/me

Creates or updates the Actor authenticated by the user access token.

Note: A PUT request overwrites the original object. Be sure to (re-)enter the values for all desired attributes.

Note 2: If the Actor does not exist yet, the {actorType}:create Policy will be evaluated. Otherwise, the {actorType}:update Policy will be evaluated.

Body parameter

{
  "customAttribute1": "value1",
  "customAttribute2": "value2"
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
tenant	path	string	true	Your tenant code.
body	body	object	true	An object specifying custom attributes for the Actor. This object must follow the JSON schema defined for ActorType.

Example responses

200 Response

{
  "id": "string",
  "type": "string",
  "customAttribute1": "string",
  "customAttribute2": "boolean"
}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» id	string	true	none	The identifier of the Actor.
» type	string	true	none	The type of the Actor.
» customAttribute	any	false	none	A property defined by the tenant for this type of object.

Authorization request template

{
  "action": "${principal.nodeType}:<createOrUpdate>",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${principal.nodeType}:<createOrUpdate>) by using the Authorization Config API.

List my Relationships

Code samples

# You can also use wget
curl -X GET /api/v1/actors/me/relationships \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/actors/me/relationships HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/actors/me/relationships',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/actors/me/relationships

List all Relationships of the Actor authenticated by the user access token.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
relationship-types	query	string	false	Optional comma-separated list of RelationshipTypes to filter on.
direction	query	string	false	Optional direction (`from` or `to`) of the Relationship with respect to the Actor authenticated by the user access token.
signed	query	boolean	false	Optional signing of Relationships. If true, the response will contain signed Relationships. The default value is false; the response contains human-readable objects.
all	query	boolean	false	Optional inclusion of reserved RelationshipTypes. If true, the response will include the RelationshipTypes predefined by Scaled Access. The default value is false.
tenant	path	string	true	Your tenant code.

Enumerated Values

Parameter	Value
direction	from
direction	to

Example responses

200 Response

[
  {
    "id": "string",
    "relationshipType": "string",
    "from": {
      "id": "string",
      "type": "string",
      "properties": {}
    },
    "to": {
      "id": "string",
      "type": "string",
      "properties": {}
    },
    "properties": {}
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
anonymous	[RelationshipDetailResponse]	false	none	none
» id	string	true	none	The identifier for the Relationship.
» relationshipType	string	true	none	The type of Relationship between the `from` and `to` Actor(s)/Resource(s).
» from	NodeDetailResponse	true	none	none
»» id	string	true	none	The identifier of the Actor/Resource.
»» type	string	true	none	The `actorType` or `resourceType` of the Actor/Resource.
»» properties	object	true	none	Custom defined properties on the node type
» to	NodeDetailResponse	true	none	none
» properties	object	false	none	The custom properties of the Relationship.

Authorization request template

{
  "action": "${principal.nodeType}:relationships:list",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "relationshipTypes": "${query[\"relationship-types\"]}",
    "direction": "${query[\"direction\"]}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${principal.nodeType}:relationships:list) by using the Authorization Config API.

Create my Relationship

Code samples

# You can also use wget
curl -X POST /api/v1/actors/me/relationships \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/actors/me/relationships HTTP/1.1

Content-Type: application/json
Accept: application/json
acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "relationshipType": "string",
  "to": {
    "id": "string",
    "type": "string"
  },
  "properties": {
    "customAttribute1": "string",
    "customAttribute2": true
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/actors/me/relationships',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/actors/me/relationships

Creates a Relationship from the Actor authenticated by the user access token to the target specified in the body.

Body parameter

{
  "relationshipType": "string",
  "to": {
    "id": "string",
    "type": "string"
  },
  "properties": {
    "customAttribute1": "string",
    "customAttribute2": true
  }
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
tenant	path	string	true	Your tenant code.
body	body	object	true	none
» relationshipType	body	string	true	The type of relationship.
» to	body	object	true	The target Actor/Resource in the Relationship.
» properties	body	object	false	The custom properties as defined in the relationship type.

Example responses

200 Response

{
  "id": "string",
  "relationshipType": "string",
  "from": {
    "id": "string",
    "type": "string",
    "properties": {}
  },
  "to": {
    "id": "string",
    "type": "string",
    "properties": {}
  },
  "properties": {}
}

Responses

Status	Meaning	Description	Schema
200	OK	none	RelationshipDetailResponse

Authorization request template

{
  "action": "${principal.nodeType}:${body.relationshipType}:${body.to.type}:create",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${principal.nodeId}",
      "type": "${principal.nodeType}"
    },
    "to": {
      "id": "${body.to.id}",
      "type": "${body.to.type}"
    },
    "relationshipType": "${body.relationshipType}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${principal.nodeType}:${body.relationshipType}:${body.to.type}:create) by using the Authorization Config API.

Get my Relationship

Code samples

# You can also use wget
curl -X GET /api/v1/actors/me/relationships/{relationshipId} \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/actors/me/relationships/{relationshipId} HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/actors/me/relationships/{relationshipId}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/actors/me/relationships/{relationshipId}

Returns the Relationship specified by {relationshipId} from the Actor authenticated by the user access token.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
relationshipId	path	string	true	The identifier for the Relationship.
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "id": "string",
  "relationshipType": "string",
  "from": {
    "id": "string",
    "type": "string",
    "properties": {}
  },
  "to": {
    "id": "string",
    "type": "string",
    "properties": {}
  },
  "properties": {}
}

Responses

Status	Meaning	Description	Schema
200	OK	none	RelationshipDetailResponse

Authorization request template

{
  "action": "${principal.nodeType}:<relationshipType>:<targetType>:read",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${principal.nodeId}",
      "type": "${principal.nodeType}"
    },
    "relationshipId": "${params.relationshipId}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${principal.nodeType}:<relationshipType>:<targetType>:read) by using the Authorization Config API.

Update my Relationship

Code samples

# You can also use wget
curl -X PUT /api/v1/actors/me/relationships/{relationshipId} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

PUT /api/v1/actors/me/relationships/{relationshipId} HTTP/1.1

Content-Type: application/json
Accept: application/json
acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "properties": {
    "customAttribute1": "string",
    "customAttribute2": true
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/actors/me/relationships/{relationshipId}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /api/v1/actors/me/relationships/{relationshipId}

Updates the Relationship specified by {relationshipId} from the Actor authenticated by the user access token.

Body parameter

{
  "properties": {
    "customAttribute1": "string",
    "customAttribute2": true
  }
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
relationshipId	path	string	true	The identifier for the Relationship.
tenant	path	string	true	Your tenant code.
body	body	object	true	none
» properties	body	object	true	The custom properties as defined in the relationship type.

Example responses

200 Response

{
  "id": "string",
  "relationshipType": "string",
  "from": {
    "id": "string",
    "type": "string",
    "properties": {}
  },
  "to": {
    "id": "string",
    "type": "string",
    "properties": {}
  },
  "properties": {}
}

Responses

Status	Meaning	Description	Schema
200	OK	none	RelationshipDetailResponse

Authorization request template

{
  "action": "${principal.nodeType}:<relationshipType>:<targetType>:update",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${principal.nodeId}",
      "type": "${principal.nodeType}"
    },
    "to": {
      "id": "<targetId>",
      "type": "<targetType>"
    },
    "relationshipType": "<relationshipType>",
    "relationshipId": "${params.relationshipId}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${principal.nodeType}:<relationshipType>:<targetType>:update) by using the Authorization Config API.

Delete my Relationship

Code samples

# You can also use wget
curl -X DELETE /api/v1/actors/me/relationships/{relationshipId} \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

DELETE /api/v1/actors/me/relationships/{relationshipId} HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/actors/me/relationships/{relationshipId}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /api/v1/actors/me/relationships/{relationshipId}

Removes the Relationship specified by {relationshipId} from the Actor authenticated by the user access token.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
relationshipId	path	string	true	The identifier for the Relationship.
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "id": "string",
  "relationshipType": "string",
  "from": {
    "id": "string",
    "type": "string",
    "properties": {}
  },
  "to": {
    "id": "string",
    "type": "string",
    "properties": {}
  },
  "properties": {}
}

Responses

Status	Meaning	Description	Schema
200	OK	none	RelationshipDetailResponse

Authorization request template

{
  "action": "${principal.nodeType}:<relationshipType>:<targetType>:delete",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${principal.nodeId}",
      "type": "${principal.nodeType}"
    },
    "to": {
      "id": "<targetId>",
      "type": "<targetType>"
    },
    "relationshipType": "<relationshipType>",
    "relationshipId": "${params.relationshipId}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${principal.nodeType}:<relationshipType>:<targetType>:delete) by using the Authorization Config API.

> Actor Endpoints

List all Actors of type

Code samples

# You can also use wget
curl -X GET /api/v1/actors/{actorType} \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/actors/{actorType} HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/actors/{actorType}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/actors/{actorType}

Returns all Actors of the specified {actorType}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
actorType	path	string	true	The type of Actor.
tenant	path	string	true	Your tenant code.

Example responses

200 Response

[
  {
    "id": "string",
    "type": "string",
    "properties": {}
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
anonymous	[ActorResponse]	false	none	none
» id	string	true	none	The identifier of the Actor.
» type	string	true	none	The type of Actor.
» properties	object	true	none	Custom defined properties on the node type

Authorization request template

{
  "action": "${params.actorType}:list",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "type": "${params.actorType}"
  }
}

Authorization Request

Create an Actor

Code samples

# You can also use wget
curl -X POST /api/v1/actors/{actorType} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/actors/{actorType} HTTP/1.1

Content-Type: application/json
Accept: application/json
acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "customAttribute1": "value1",
  "customAttribute2": "value2"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/actors/{actorType}',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/actors/{actorType}

Creates an Actor of type {actorType}. The system will assign an actorId.

Body parameter

{
  "customAttribute1": "value1",
  "customAttribute2": "value2"
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
actorType	path	string	true	The type of Actor.
tenant	path	string	true	Your tenant code.
body	body	object	true	An object specifying custom attributes for the Actor. This object must follow the JSON schema defined for the chosen ActorType.

Example responses

201 Response

{
  "id": "string",
  "type": "string",
  "customAttribute1": "string",
  "customAttribute2": "boolean"
}

Responses

Status	Meaning	Description	Schema
201	Created	none	Inline

Response Schema

Status Code 201

Name	Type	Required	Restrictions	Description
» id	string	true	none	The identifier of the Actor.
» type	string	true	none	The type of the Actor.
» customAttribute	any	false	none	A property defined by the tenant for this type of object.

Authorization request template

{
  "action": "${params.actorType}:create",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "type": "${params.actorType}"
  }
}

Authorization Request

Get an Actor

Code samples

# You can also use wget
curl -X GET /api/v1/actors/{actorType}/{actorId} \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/actors/{actorType}/{actorId} HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/actors/{actorType}/{actorId}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/actors/{actorType}/{actorId}

Returns the Actor specified by {actorType} and {actorId}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
actorType	path	string	true	The type of Actor.
actorId	path	string	true	The identifier for the Actor.
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "id": "string",
  "type": "string",
  "customAttribute1": "string",
  "customAttribute2": "boolean"
}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» id	string	true	none	The identifier of the Actor.
» type	string	true	none	The type of the Actor.
» customAttribute	any	false	none	A property defined by the tenant for this type of object.

Authorization request template

{
  "action": "${params.actorType}:read",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${params.actorId}",
    "type": "${params.actorType}"
  }
}

Authorization Request

Create/update an Actor

Code samples

# You can also use wget
curl -X PUT /api/v1/actors/{actorType}/{actorId} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

PUT /api/v1/actors/{actorType}/{actorId} HTTP/1.1

Content-Type: application/json
Accept: application/json
acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "customAttribute1": "value1",
  "customAttribute2": "value2"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/actors/{actorType}/{actorId}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /api/v1/actors/{actorType}/{actorId}

Creates or updates the Actor specified by {actorType} and {actorId}.

Note: A PUT request overwrites the original object. Be sure to (re-)enter the values for all desired attributes.

Note 2: If the Actor does not exist yet, the {actorType}:create Policy will be evaluated. Otherwise, the {actorType}:update Policy will be evaluated.

Body parameter

{
  "customAttribute1": "value1",
  "customAttribute2": "value2"
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
actorType	path	string	true	The type of Actor.
actorId	path	string	true	The identifier for the Actor.
tenant	path	string	true	Your tenant code.
body	body	object	true	An object specifying custom attributes for the Actor. This object must follow the JSON schema defined for the chosen ActorType.

Example responses

200 Response

{
  "id": "string",
  "type": "string",
  "customAttribute1": "string",
  "customAttribute2": "boolean"
}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» id	string	true	none	The identifier of the Actor.
» type	string	true	none	The type of the Actor.
» customAttribute	any	false	none	A property defined by the tenant for this type of object.

Authorization request template

{
  "action": "${params.actorType}:<createOrUpdate>",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${params.actorId}",
    "type": "${params.actorType}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.actorType}:<createOrUpdate>) by using the Authorization Config API.

Delete an Actor

Code samples

# You can also use wget
curl -X DELETE /api/v1/actors/{actorType}/{actorId} \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

DELETE /api/v1/actors/{actorType}/{actorId} HTTP/1.1

acting-tenant-id: string
tenant-id: string


const headers = {
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/actors/{actorType}/{actorId}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /api/v1/actors/{actorType}/{actorId}

Removes the Actor specified by {actorType} and {actorId}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
actorType	path	string	true	The type of Actor.
actorId	path	string	true	The identifier for the Actor.
tenant	path	string	true	Your tenant code.

Responses

Status	Meaning	Description	Schema
200	OK	none	None

Authorization request template

{
  "action": "${params.actorType}:delete",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${params.actorId}",
    "type": "${params.actorType}"
  }
}

Authorization Request

List all Relationships

Code samples

# You can also use wget
curl -X GET /api/v1/actors/{actorType}/{actorId}/relationships \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/actors/{actorType}/{actorId}/relationships HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/actors/{actorType}/{actorId}/relationships',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/actors/{actorType}/{actorId}/relationships

Returns all Relationships of the Actor specified by {actorType} and {actorId}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
actorType	path	string	true	The type of Actor.
actorId	path	string	true	The identifier for the Actor.
relationship-types	query	string	false	Optional comma-separated list of RelationshipTypes to filter on.
direction	query	string	false	Optional direction (`from` or `to`) of the Relationship with respect to the Actor specified by {actorType} and {actorId}.
signed	query	boolean	false	Optional signing of Relationships. If true, the response will contain signed Relationships. The default value is false; the response contains human-readable objects.
all	query	boolean	false	Optional inclusion of reserved RelationshipTypes. If true, the response will include the RelationshipTypes predefined by Scaled Access. The default value is false.
tenant	path	string	true	Your tenant code.

Enumerated Values

Parameter	Value
direction	from
direction	to

Example responses

200 Response

[
  {
    "id": "string",
    "relationshipType": "string",
    "from": {
      "id": "string",
      "type": "string",
      "properties": {}
    },
    "to": {
      "id": "string",
      "type": "string",
      "properties": {}
    },
    "properties": {}
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
anonymous	[RelationshipDetailResponse]	false	none	none
» id	string	true	none	The identifier for the Relationship.
» relationshipType	string	true	none	The type of Relationship between the `from` and `to` Actor(s)/Resource(s).
» from	NodeDetailResponse	true	none	none
»» id	string	true	none	The identifier of the Actor/Resource.
»» type	string	true	none	The `actorType` or `resourceType` of the Actor/Resource.
»» properties	object	true	none	Custom defined properties on the node type
» to	NodeDetailResponse	true	none	none
» properties	object	false	none	The custom properties of the Relationship.

Authorization request template

{
  "action": "${params.actorType}:relationships:list",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${params.actorId}",
    "type": "${params.actorType}",
    "relationshipTypes": "${query[\"relationship-types\"]}",
    "direction": "${query[\"direction\"]}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.actorType}:relationships:list) by using the Authorization Config API.

Create a Relationship

Code samples

# You can also use wget
curl -X POST /api/v1/actors/{actorType}/{actorId}/relationships \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/actors/{actorType}/{actorId}/relationships HTTP/1.1

Content-Type: application/json
Accept: application/json
acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "relationshipType": "string",
  "to": {
    "id": "string",
    "type": "string"
  },
  "properties": {
    "customAttribute1": "string",
    "customAttribute2": true
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/actors/{actorType}/{actorId}/relationships',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/actors/{actorType}/{actorId}/relationships

Creates a Relationship from the Actor specified by {actorType} and {actorId} to the target specified in the body.

Body parameter

{
  "relationshipType": "string",
  "to": {
    "id": "string",
    "type": "string"
  },
  "properties": {
    "customAttribute1": "string",
    "customAttribute2": true
  }
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
actorType	path	string	true	The type of Actor.
actorId	path	string	true	The identifier for the Actor.
tenant	path	string	true	Your tenant code.
body	body	object	true	none
» relationshipType	body	string	true	The type of relationship.
» to	body	object	true	The target Actor/Resource in the Relationship.
» properties	body	object	false	The custom properties as defined in the relationship type.

Example responses

200 Response

{
  "id": "string",
  "relationshipType": "string",
  "from": {
    "id": "string",
    "type": "string",
    "properties": {}
  },
  "to": {
    "id": "string",
    "type": "string",
    "properties": {}
  },
  "properties": {}
}

Responses

Status	Meaning	Description	Schema
200	OK	none	RelationshipDetailResponse

Authorization request template

{
  "action": "${params.actorType}:${body.relationshipType}:${body.to.type}:create",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${params.actorId}",
      "type": "${params.actorType}"
    },
    "to": {
      "id": "${body.to.id}",
      "type": "${body.to.type}"
    },
    "relationshipType": "${body.relationshipType}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.actorType}:${body.relationshipType}:${body.to.type}:create) by using the Authorization Config API.

Delete a Relationship

Code samples

# You can also use wget
curl -X DELETE /api/v1/actors/{actorType}/{actorId}/relationships/{relationshipId} \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

DELETE /api/v1/actors/{actorType}/{actorId}/relationships/{relationshipId} HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/actors/{actorType}/{actorId}/relationships/{relationshipId}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /api/v1/actors/{actorType}/{actorId}/relationships/{relationshipId}

Removes the Relationship specified by {relationshipId}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
actorId	path	string	true	The identifier for the Actor.
actorType	path	string	true	The type of Actor.
relationshipId	path	string	true	The identifier for the Relationship.
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "id": "string",
  "relationshipType": "string",
  "from": {
    "id": "string",
    "type": "string",
    "properties": {}
  },
  "to": {
    "id": "string",
    "type": "string",
    "properties": {}
  },
  "properties": {}
}

Responses

Status	Meaning	Description	Schema
200	OK	none	RelationshipDetailResponse

Authorization request template

{
  "action": "${params.actorType}:<relationshipType>:<targetType>:delete",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${params.actorId}",
      "type": "${params.actorType}"
    },
    "to": {
      "id": "<targetId>",
      "type": "<targetType>"
    },
    "relationshipType": "<relationshipType>",
    "relationshipId": "${params.relationshipId}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.actorType}:<relationshipType>:<targetType>:delete) by using the Authorization Config API.

Get a Relationship

Code samples

# You can also use wget
curl -X GET /api/v1/actors/{actorType}/{actorId}/relationships/{relationshipId} \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/actors/{actorType}/{actorId}/relationships/{relationshipId} HTTP/1.1

acting-tenant-id: string
tenant-id: string


const headers = {
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/actors/{actorType}/{actorId}/relationships/{relationshipId}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/actors/{actorType}/{actorId}/relationships/{relationshipId}

Gets the Relationship specified by {relationshipId}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
actorId	path	string	true	The identifier for the Actor.
actorType	path	string	true	The type of Actor.
relationshipId	path	string	true	The identifier for the Relationship.
tenant	path	string	true	Your tenant code.

Responses

Status	Meaning	Description	Schema
200	OK	none	None

Authorization request template

{
  "action": "${params.actorType}:<relationshipType>:<targetType>:read",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${params.actorId}",
      "type": "${params.actorType}"
    },
    "to": {
      "id": "<targetId>",
      "type": "<targetType>"
    },
    "relationshipType": "<relationshipType>",
    "relationshipId": "${params.relationshipId}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.actorType}:<relationshipType>:<targetType>:read) by using the Authorization Config API.

Update a Relationship

Code samples

# You can also use wget
curl -X PUT /api/v1/actors/{actorType}/{actorId}/relationships/{relationshipId} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

PUT /api/v1/actors/{actorType}/{actorId}/relationships/{relationshipId} HTTP/1.1

Content-Type: application/json
Accept: application/json
acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "properties": {
    "customAttribute1": "string",
    "customAttribute2": true
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/actors/{actorType}/{actorId}/relationships/{relationshipId}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /api/v1/actors/{actorType}/{actorId}/relationships/{relationshipId}

Update a Relationship of the Actor specified by {actorType}, {actorId} and {relationshipId}

Body parameter

{
  "properties": {
    "customAttribute1": "string",
    "customAttribute2": true
  }
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
actorType	path	string	true	The type of Actor.
actorId	path	string	true	The identifier for the Actor.
relationshipId	path	string	true	The identifier for the Relationship.
tenant	path	string	true	Your tenant code.
body	body	object	true	none
» properties	body	object	true	The custom properties as defined in the relationship type.

Example responses

200 Response

{
  "id": "string",
  "relationshipType": "string",
  "from": {
    "id": "string",
    "type": "string",
    "properties": {}
  },
  "to": {
    "id": "string",
    "type": "string",
    "properties": {}
  },
  "properties": {}
}

Responses

Status	Meaning	Description	Schema
200	OK	none	RelationshipDetailResponse

Authorization request template

{
  "action": "${params.actorType}:<relationshipType>:<targetType>:update",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${params.actorId}",
      "type": "${params.actorType}"
    },
    "to": {
      "id": "<targetId>",
      "type": "<targetType>"
    },
    "relationshipType": "<relationshipType>",
    "relationshipId": "${params.relationshipId}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.actorType}:<relationshipType>:<targetType>:update) by using the Authorization Config API.

> Invitation Endpoints

List my Invitations

Code samples

# You can also use wget
curl -X GET /api/v1/sharing/invitations/me \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/sharing/invitations/me HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/sharing/invitations/me',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/sharing/invitations/me

Lists all Invitations linked to the Actor authenticated by the user access token.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
relationship-types	query	string	false	Optional comma-separated list of RelationshipTypes to filter on: `isCreatedBy`, `targets`, `isAcceptedBy` and `isRevokedBy`.
tenant	path	string	true	Your tenant code.

Example responses

200 Response

[
  {
    "invitationId": "string",
    "relationships": [
      {
        "relationshipType": "string",
        "relationshipDirectionForSubject": "from",
        "targets": {
          "id": "string",
          "type": "string"
        }
      }
    ],
    "expiryDate": 1613554476,
    "inviteeContactType": "email",
    "inviteeContactValue": "invitee@example.com",
    "isCreatedBy": {
      "id": "string",
      "type": "user"
    },
    "isAcceptedBy": {
      "id": "string",
      "type": "user"
    }
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» invitationId	string	true	none	An identifier for the Invitation.
» relationships	[object]	true	none	A list of relationships suggested for the invitee.
»» relationshipType	string	false	none	The type of relationship suggested for the invitee and the target.
»» relationshipDirectionForSubject	string	false	none	The role suggested for the subject, i.e. the invitee, in the Relationship. The Relationship can start from (`from`) or end at (`to`) the subject.
»» targets	object	false	none	The Actor/Resource for which a Relationship is suggested in the invitation.
» expiryDate	number	true	none	The expiry date of the invitation, as a unix timestamp in seconds.
» inviteeContactType	string	false	none	The type of contact information available for the invitee.
» inviteeContactValue	string	false	none	The contact information of the invitee.
» isCreatedBy	object	false	none	The Actor that requested the invitation.
» isAcceptedBy	object	false	none	The Actor that accepted the invitation.
» isRevokedBy	object	false	none	The Actor that withdrew the invitation.

Authorization request template

{
  "action": "invitation:list",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}"
  }
}

Authorization Request

List all Invitations

Code samples

# You can also use wget
curl -X GET /api/v1/sharing/invitations?id=string&type=string \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/sharing/invitations?id=string&type=string HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/sharing/invitations?id=string&type=string',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/sharing/invitations

Lists all Invitations linked to the Actor or Resource specified by the query parameters {id} and {type}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
id	query	string	true	The `actorId` or `resourceId` of the Actor/Resource for which to find Invitations.
type	query	string	true	The `actorType` or `resourceType` of the Actor/Resource for which to find Invitations.
relationship-types	query	string	false	Optional comma-separated list of RelationshipTypes to filter on: `isCreatedBy`, `targets`, `isAcceptedBy` and `isRevokedBy`.
tenant	path	string	true	Your tenant code.

Example responses

200 Response

[
  {
    "invitationId": "string",
    "relationships": [
      {
        "relationshipType": "string",
        "relationshipDirectionForSubject": "from",
        "targets": {
          "id": "string",
          "type": "string"
        }
      }
    ],
    "expiryDate": 1613554476,
    "inviteeContactType": "email",
    "inviteeContactValue": "invitee@example.com",
    "isCreatedBy": {
      "id": "string",
      "type": "user"
    },
    "isAcceptedBy": {
      "id": "string",
      "type": "user"
    }
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» invitationId	string	true	none	An identifier for the Invitation.
» relationships	[object]	true	none	A list of relationships suggested for the invitee.
»» relationshipType	string	false	none	The type of relationship suggested for the invitee and the target.
»» relationshipDirectionForSubject	string	false	none	The role suggested for the subject, i.e. the invitee, in the Relationship. The Relationship can start from (`from`) or end at (`to`) the subject.
»» targets	object	false	none	The Actor/Resource for which a Relationship is suggested in the invitation.
» expiryDate	number	true	none	The expiry date of the invitation, as a unix timestamp in seconds.
» inviteeContactType	string	false	none	The type of contact information available for the invitee.
» inviteeContactValue	string	false	none	The contact information of the invitee.
» isCreatedBy	object	false	none	The Actor that requested the invitation.
» isAcceptedBy	object	false	none	The Actor that accepted the invitation.
» isRevokedBy	object	false	none	The Actor that withdrew the invitation.

Authorization request template

{
  "action": "invitation:list",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${query[\"id\"]}",
    "type": "${query[\"type\"]}"
  }
}

Authorization Request

Create an Invitation

Code samples

# You can also use wget
curl -X POST /api/v1/sharing/invitations \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/sharing/invitations HTTP/1.1

Content-Type: application/json
Accept: application/json
acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "relationships": [
    {
      "relationshipType": "string",
      "to": {
        "id": "string",
        "type": "string"
      }
    }
  ],
  "invitor": {
    "id": "string",
    "type": "string"
  },
  "invitee": {
    "contact": {
      "type": "email",
      "value": "string"
    }
  },
  "expiryDate": 1613485553
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/sharing/invitations',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/sharing/invitations

Creates an Invitation for the invitee to form a Relationship with the target Actor/Resource. The target must be specified with either the from or to body parameter.

Body parameter

{
  "relationships": [
    {
      "relationshipType": "string",
      "to": {
        "id": "string",
        "type": "string"
      }
    }
  ],
  "invitor": {
    "id": "string",
    "type": "string"
  },
  "invitee": {
    "contact": {
      "type": "email",
      "value": "string"
    }
  },
  "expiryDate": 1613485553
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
body	body	object	true	none
» relationships	body	[object]	true	A list of relationships
»» relationshipType	body	string	false	The type of relationship suggested for the invitee and the target.
»» from	body	object	false	The target Actor/Resource in the Relationship. Choose `from` or `to` to indicate the direction of the Relationship.
»» to	body	object	false	The target Actor/Resource in the Relationship. Choose `from` or `to` to indicate the direction of the Relationship.
»» properties	body	object	false	An object with any extra properties that the relationship type requires or allows.
» invitor	body	object	false	The Actor who requests the invitation. If not provided, the subject from the access token will be used as Actor (if a subject is present).
» invitee	body	object	false	The actor who is invited to form a Relationship.
»» contact	body	object	false	Contact information.
»»» type	body	string	true	The type of contact information. This value must be set to `email`.
»»» value	body	string	true	An email address.
» expiryDate	body	number	false	An expiry date as unix timestamp in seconds. If not provided, the expiry date will be set 24 hours in the future.

Enumerated Values

Parameter	Value
»»» type	email

Example responses

201 Response

{
  "invitationId": "string",
  "requestToken": "string"
}

Responses

Status	Meaning	Description	Schema
201	Created	The Invitation is created. The `invitationId` or `requestToken` in the response body can be used by the client in a subsequent request to the Relationship Management API to accept the invitation on request of the invitee. The Relationship Management API will validate whether a provided `requestToken` is still valid, whereas it will accept an `invitationId` without validation.	CreateInvitationResponse

Authorization request template

{
  "action": "${!!body.relationships?.from ? body.relationships.from.type : 'user'}:${body.relationships.relationshipType}:${body.relationships.from ? 'user' : body.relationships.to.type}:invitation:create",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${!!body.relationships.from ? body.relationships.from.id : ''}",
      "type": "${!!body.relationships.from ? body.relationships.from.type : 'user'}"
    },
    "to": {
      "id": "${!!body.relationships.to ? body.relationships.to.id : ''}",
      "type": "${!!body.relationships.to ? body.relationships.to.type : 'user'}"
    },
    "direction": "${!!body.relationships.from ? \"from\" : \"to\"}",
    "invitor": {
      "id": "${body.invitor && body.invitor.id || principal.nodeId}",
      "type": "${body.invitor && body.invitor.type || principal.nodeType}"
    },
    "relationshipType": "${body.relationships.relationshipType}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${!!body.relationships?.from ? body.relationships.from.type : 'user'}:${body.relationships.relationshipType}:${body.relationships.from ? 'user' : body.relationships.to.type}:invitation:create) by using the Authorization Config API.

Get an invitation

Code samples

# You can also use wget
curl -X GET /api/v1/sharing/invitations/{invitationId} \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/sharing/invitations/{invitationId} HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/sharing/invitations/{invitationId}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/sharing/invitations/{invitationId}

Returns the Invitation specified by {invitationId}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
invitationId	path	string	true	The identifier for the Invitation.
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "id": "string",
  "type": "invitation",
  "relationships": [
    {
      "relationshipType": "string",
      "relationshipDirectionForSubject": "from",
      "targets": {
        "id": "string",
        "type": "string"
      }
    }
  ],
  "expiryDate": 1613554331,
  "inviteeContactType": "email",
  "inviteeContactValue": "invitee@example.com",
  "isCreatedBy": {
    "id": "string",
    "type": "user"
  },
  "isAcceptedBy": {
    "id": "string",
    "type": "user"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» id	string	true	none	The identifier for the Invitation.
» type	string	true	none	The type of Object, an Invitation.
» relationships	[object]	true	none	A list of relationships suggested for the invitee.
»» relationshipType	string	false	none	The type of relationship suggested for the invitee and the target.
»» relationshipDirectionForSubject	string	false	none	The role suggested for the subject, i.e. the invitee, in the Relationship. The Relationship can start from (`from`) or end at (`to`) the subject.
»» targets	object	false	none	The Actor/Resource for which a Relationship is suggested in the invitation.
» expiryDate	number	true	none	The expiry date of the invitation, as a unix timestamp in seconds.
» inviteeContactType	string	false	none	The type of contact information available for the invitee.
» inviteeContactValue	string	false	none	The contact information of the invitee.
» isCreatedBy	object	false	none	The Actor that requested the invitation.
» isAcceptedBy	object	false	none	The Actor that accepted the invitation.
» isRevokedBy	object	false	none	The Actor that withdrew the invitation.

Authorization request template

{
  "action": "<relationshipSourceType>:<relationshipType>:<relationshipTargetType>:invitation:read",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${params.invitationId}",
    "type": "invitation"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case <relationshipSourceType>:<relationshipType>:<relationshipTargetType>:invitation:read) by using the Authorization Config API.

Refresh an Invitation

Code samples

# You can also use wget
curl -X PUT /api/v1/sharing/invitations/{invitationId} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

PUT /api/v1/sharing/invitations/{invitationId} HTTP/1.1

Content-Type: application/json
Accept: application/json
acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "expiryDate": 0
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/sharing/invitations/{invitationId}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /api/v1/sharing/invitations/{invitationId}

Refreshes an Invitation by creating a new token for the Invitation. This can be used if the old token has expired or is no longer available and you want to resend the invitation.

Body parameter

{
  "expiryDate": 0
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
invitationId	path	string	true	The identifier for the Invitation.
tenant	path	string	true	Your tenant code.
body	body	object	true	none

Example responses

201 Response

{
  "invitationId": "string",
  "requestToken": "string"
}

Responses

Status	Meaning	Description	Schema
201	Created	The Invitation is refreshed. The `invitationId` or `requestToken` in the response body can be used by the client in a subsequent request to the Relationship Management API to accept the invitation on request of the invitee. The Relationship Management API will validate whether a provided `requestToken` is still valid, whereas it will accept an `invitationId` without validation.	CreateInvitationResponse

Authorization request template

{
  "action": "<relationshipSourceType>:<relationshipType>:<relationshipTargetType>:invitation:refresh",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${params.invitationId}",
    "type": "invitation"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case <relationshipSourceType>:<relationshipType>:<relationshipTargetType>:invitation:refresh) by using the Authorization Config API.

Accept an Invitation

Code samples

# You can also use wget
curl -X POST /api/v1/sharing/invitations/accept \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/sharing/invitations/accept HTTP/1.1

Content-Type: application/json
Accept: application/json
acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "acceptor": {
    "id": "string",
    "type": "string"
  },
  "requestToken": "string",
  "properties": {
    "isActive": "true"
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/sharing/invitations/accept',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/sharing/invitations/accept

Accepts an Invitation and creates the specified Relationship between the invitee and the target. The Invitation must be specified in the body by either the requestToken (valid for 24 hours after its creation) or invitationId obtained when creating the Invitation. This endpoint can be used by the invitee or by a third party (e.g. a back-office or automatic system) to accept an invitation on request of the invitee.

Note: Make sure that the acceptor.id and acceptor.type correlate with the claims in the invitee's user access token (see Integration of access token claims). If no Actor object exists for the provided acceptor.id and acceptor.type, a new Actor with the provided id and type is automatically created.

Body parameter

{
  "acceptor": {
    "id": "string",
    "type": "string"
  },
  "requestToken": "string",
  "properties": {
    "isActive": "true"
  }
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
tenant	path	string	true	Your tenant code.
body	body	object	true	none
» acceptor	body	object	false	The Actor accepting the invitation. If not provided, the subject from the access token will be used as Actor.
»» id	body	string	true	The identifier of the Actor.
»» type	body	string	true	The type of Actor.
» invitationId	body	string	false	The identifier of the Invitation. Provide either the `requestToken` or `invitationId`.
» requestToken	body	string	false	The request token obtained when creating the Invitation. Provide either the `requestToken` or `invitationId`.
» properties	body	object	false	An object with any extra properties that the relationship type requires or allows. Only strings are allowed.

Example responses

200 Response

{
  "id": "string",
  "type": "invitation",
  "relationships": [
    {
      "relationshipType": "string",
      "relationshipDirectionForSubject": "from",
      "targets": {
        "id": "string",
        "type": "string"
      }
    }
  ],
  "expiryDate": 1613554331,
  "inviteeContactType": "email",
  "inviteeContactValue": "invitee@example.com",
  "isCreatedBy": {
    "id": "string",
    "type": "user"
  },
  "isAcceptedBy": {
    "id": "string",
    "type": "user"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» id	string	true	none	The identifier for the Invitation.
» type	string	true	none	The type of Object, an Invitation.
» relationships	[object]	true	none	A list of relationships suggested for the invitee.
»» relationshipType	string	false	none	The type of relationship suggested for the invitee and the target.
»» relationshipDirectionForSubject	string	false	none	The role suggested for the subject, i.e. the invitee, in the Relationship. The Relationship can start from (`from`) or end at (`to`) the subject.
»» targets	object	false	none	The Actor/Resource for which a Relationship is suggested in the invitation.
» expiryDate	number	true	none	The expiry date of the invitation, as a unix timestamp in seconds.
» inviteeContactType	string	false	none	The type of contact information available for the invitee.
» inviteeContactValue	string	false	none	The contact information of the invitee.
» isCreatedBy	object	false	none	The Actor that requested the invitation.
» isAcceptedBy	object	false	none	The Actor that accepted the invitation.
» isRevokedBy	object	false	none	The Actor that withdrew the invitation.

Authorization request template

{
  "action": "invitation:accept",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${body.acceptor && body.acceptor.id || accessToken.nodeId}",
    "type": "${body.acceptor && body.acceptor.type || accessToken.nodeType}",
    "invitationId": "${body.invitationId}",
    "requestToken": "${body.requestToken || undefined}"
  }
}

Authorization Request

Withdraw an Invitation

Code samples

# You can also use wget
curl -X POST /api/v1/sharing/invitations/withdraw \
  -H 'Content-Type: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/sharing/invitations/withdraw HTTP/1.1

Content-Type: application/json

acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "revocator": {
    "id": "string",
    "type": "string"
  },
  "invitationId": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/sharing/invitations/withdraw',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/sharing/invitations/withdraw

Withdraws an Invitation.

Body parameter

{
  "revocator": {
    "id": "string",
    "type": "string"
  },
  "invitationId": "string"
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
tenant	path	string	true	Your tenant code.
body	body	object	true	none
» revocator	body	object	false	The Actor withdrawing the invitation. If not provided, the subject from the access token will be used as Actor.
»» id	body	string	true	The identifier of the Actor.
»» type	body	string	true	The type of Actor.
» invitationId	body	string	true	The identifier of the Invitation.

Responses

Status	Meaning	Description	Schema
200	OK	The invitee can no longer accept the Invitation.	None

Authorization request template

{
  "action": "<relationshipSourceType>:<relationshipType>:<relationshipTargetType>:invitation:withdraw",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${body.invitationId}",
    "type": "invitation"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case <relationshipSourceType>:<relationshipType>:<relationshipTargetType>:invitation:withdraw) by using the Authorization Config API.

> Approval Request Endpoints

List my approval requests

Code samples

# You can also use wget
curl -X GET /api/v1/sharing/approval-requests/me \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/sharing/approval-requests/me HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/sharing/approval-requests/me',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/sharing/approval-requests/me

Lists all Approval Requests linked to the Actor authenticated by the user access token.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
tenant	path	string	true	Your tenant code.

Example responses

200 Response

[
  {
    "id": "123",
    "type": "approvalrequest",
    "relationshipType": "is_member_of",
    "approvalRequestType": "relationship",
    "from": {
      "id": "user1",
      "type": "user"
    },
    "to": {
      "id": "user2",
      "type": "user"
    },
    "initiates": {
      "id": "user3",
      "type": "user"
    }
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» id	string	true	none	The identifier for the Approval Request.
» type	string	true	none	The type of object, an Approval Request.
» relationshipType	string	true	none	The type of relationship to be created once the approval request is approved.
» approvalRequestType	string	true	none	The type of approval request.
» from	object	false	none	The target associated with the approval request's relationship origin
»» id	string	false	none	none
»» type	string	false	none	none
» to	object	false	none	The target associated with the approval request's relationship target
»» id	string	false	none	none
»» type	string	false	none	none
» approves	object	false	none	The Actor that approves the Approval Request.
»» id	string	false	none	none
»» type	string	false	none	none
» denies	object	false	none	The Actor that denies the Approval Request.
»» id	string	false	none	none
»» type	string	false	none	none
» initiates	object	false	none	The Actor that initiated the Approval Request
»» id	string	false	none	none
»» type	string	false	none	none

Authorization request template

{
  "action": "approvalrequest:list",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}"
  }
}

Authorization Request

List all Approval Requests

Code samples

# You can also use wget
curl -X GET /api/v1/sharing/approval-requests?id=string&type=string \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/sharing/approval-requests?id=string&type=string HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/sharing/approval-requests?id=string&type=string',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/sharing/approval-requests

Lists all Approval Requests linked to the Actor or Resource specified by the query parameters {id} and {type}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
id	query	string	true	The `actorId` or `resourceId` of the Actor/Resource for which to find Approval Requests.
type	query	string	true	The `actorType` or `resourceType` of the Actor/Resource for which to find Approval Requests.
tenant	path	string	true	Your tenant code.

Example responses

200 Response

[
  {
    "id": "123",
    "type": "approvalrequest",
    "relationshipType": "is_member_of",
    "approvalRequestType": "relationship",
    "from": {
      "id": "user1",
      "type": "user"
    },
    "to": {
      "id": "user2",
      "type": "user"
    },
    "initiates": {
      "id": "user3",
      "type": "user"
    }
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» id	string	true	none	The identifier for the Approval Request.
» type	string	true	none	The type of object, an Approval Request.
» relationshipType	string	true	none	The type of relationship to be created once the approval request is approved.
» approvalRequestType	string	true	none	The type of approval request.
» from	object	false	none	The target associated with the approval request's relationship origin
»» id	string	false	none	none
»» type	string	false	none	none
» to	object	false	none	The target associated with the approval request's relationship target
»» id	string	false	none	none
»» type	string	false	none	none
» approves	object	false	none	The Actor that approves the Approval Request.
»» id	string	false	none	none
»» type	string	false	none	none
» denies	object	false	none	The Actor that denies the Approval Request.
»» id	string	false	none	none
»» type	string	false	none	none
» initiates	object	false	none	The Actor that initiated the Approval Request
»» id	string	false	none	none
»» type	string	false	none	none

Authorization request template

{
  "action": "approvalrequest:list",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${query[\"id\"]}",
    "type": "${query[\"type\"]}"
  }
}

Authorization Request

Create an Approval Request

Code samples

# You can also use wget
curl -X POST /api/v1/sharing/approval-requests \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/sharing/approval-requests HTTP/1.1

Content-Type: application/json
Accept: application/json
acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "approvalRequestType": "relationship",
  "relationshipType": "string",
  "from": {
    "id": "string",
    "type": "string"
  },
  "to": {
    "id": "string",
    "type": "string"
  },
  "initiator": {
    "id": "string",
    "type": "string"
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/sharing/approval-requests',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/sharing/approval-requests

Creates an Approval Request to form a Relationship between the the given actors/resources

Body parameter

{
  "approvalRequestType": "relationship",
  "relationshipType": "string",
  "from": {
    "id": "string",
    "type": "string"
  },
  "to": {
    "id": "string",
    "type": "string"
  },
  "initiator": {
    "id": "string",
    "type": "string"
  }
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
body	body	CreateApprovalRequestRequest	true	none

Example responses

201 Response

{
  "approvalRequestId": "string"
}

Responses

Status	Meaning	Description	Schema
201	Created	The Approval Request is created. The `approvalRequestId` in the response body can be used by the client in a subsequent request to the Relationship Management API to approve the approval request.	CreateApprovalRequestResponse

Authorization request template

{
  "action": "${body.from.type}:${body.relationshipType}:${body.to.type}:approvalrequest:create",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${body.from.id}",
      "type": "${body.from.type}"
    },
    "to": {
      "id": "${body.to.id}",
      "type": "${body.to.type}"
    },
    "initiator": {
      "id": "${principal.nodeId}",
      "type": "${principal.nodeType}"
    },
    "relationshipType": "${body.relationshipType}",
    "approvalRequestType": "${body.approvalRequestType}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${body.from.type}:${body.relationshipType}:${body.to.type}:approvalrequest:create) by using the Authorization Config API.

Get an Approval Request

Code samples

# You can also use wget
curl -X GET /api/v1/sharing/approval-requests/{approvalRequestId} \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/sharing/approval-requests/{approvalRequestId} HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/sharing/approval-requests/{approvalRequestId}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/sharing/approval-requests/{approvalRequestId}

Returns the Approval Request specified by {approvalRequestId}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
approvalRequestId	path	string	true	The identifier for the ApprovalRequest.
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "id": "123",
  "type": "approvalrequest",
  "relationshipType": "is_member_of",
  "approvalRequestType": "relationship",
  "from": {
    "id": "user1",
    "type": "user"
  },
  "to": {
    "id": "user2",
    "type": "user"
  },
  "initiates": {
    "id": "user3",
    "type": "user"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» id	string	true	none	The identifier for the Approval Request.
» type	string	true	none	The type of object, an Approval Request.
» relationshipType	string	true	none	The type of relationship to be created once the approval request is approved.
» approvalRequestType	string	true	none	The type of approval request.
» from	object	false	none	The target associated with the approval request's relationship origin
»» id	string	false	none	none
»» type	string	false	none	none
» to	object	false	none	The target associated with the approval request's relationship target
»» id	string	false	none	none
»» type	string	false	none	none
» approves	object	false	none	The Actor that approves the Approval Request.
»» id	string	false	none	none
»» type	string	false	none	none
» denies	object	false	none	The Actor that denies the Approval Request.
»» id	string	false	none	none
»» type	string	false	none	none
» initiates	object	false	none	The Actor that initiated the Approval Request
»» id	string	false	none	none
»» type	string	false	none	none

Authorization request template

{
  "action": "approvalrequest:read",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${params.invitationId}",
    "type": "approvalrequest"
  }
}

Authorization Request

Approve an Approval Request

Code samples

# You can also use wget
curl -X POST /api/v1/sharing/approval-requests/approve \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/sharing/approval-requests/approve HTTP/1.1

Content-Type: application/json
Accept: application/json
acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "approvalRequestId": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/sharing/approval-requests/approve',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/sharing/approval-requests/approve

Accepts an Approval Request and creates the specified Relationship between the (from) target and the (to) target.

Body parameter

{
  "approvalRequestId": "string"
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
tenant	path	string	true	Your tenant code.
body	body	ApproveApprovalRequestRequest	true	none

Example responses

200 Response

{
  "id": "123",
  "type": "approvalrequest",
  "relationshipType": "is_member_of",
  "approvalRequestType": "relationship",
  "from": {
    "id": "user1",
    "type": "user"
  },
  "to": {
    "id": "user2",
    "type": "user"
  },
  "initiates": {
    "id": "user3",
    "type": "user"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» id	string	true	none	The identifier for the Approval Request.
» type	string	true	none	The type of object, an Approval Request.
» relationshipType	string	true	none	The type of relationship to be created once the approval request is approved.
» approvalRequestType	string	true	none	The type of approval request.
» from	object	false	none	The target associated with the approval request's relationship origin
»» id	string	false	none	none
»» type	string	false	none	none
» to	object	false	none	The target associated with the approval request's relationship target
»» id	string	false	none	none
»» type	string	false	none	none
» approves	object	false	none	The Actor that approves the Approval Request.
»» id	string	false	none	none
»» type	string	false	none	none
» denies	object	false	none	The Actor that denies the Approval Request.
»» id	string	false	none	none
»» type	string	false	none	none
» initiates	object	false	none	The Actor that initiated the Approval Request
»» id	string	false	none	none
»» type	string	false	none	none

Authorization request template

{
  "action": "<approvalTarget>:approvalrequest:approve",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${body.approvalRequestId}",
    "type": "approvalrequest"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case <approvalTarget>:approvalrequest:approve) by using the Authorization Config API.

Deny an Approval Request

Code samples

# You can also use wget
curl -X POST /api/v1/sharing/approval-requests/deny \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/sharing/approval-requests/deny HTTP/1.1

Content-Type: application/json
Accept: application/json
acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "approvalRequestId": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/sharing/approval-requests/deny',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/sharing/approval-requests/deny

Denies an Approval Request.

Body parameter

{
  "approvalRequestId": "string"
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
tenant	path	string	true	Your tenant code.
body	body	DenyApprovalRequestRequest	true	none

Example responses

200 Response

{
  "id": "123",
  "type": "approvalrequest",
  "relationshipType": "is_member_of",
  "approvalRequestType": "relationship",
  "from": {
    "id": "user1",
    "type": "user"
  },
  "to": {
    "id": "user2",
    "type": "user"
  },
  "initiates": {
    "id": "user3",
    "type": "user"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» id	string	true	none	The identifier for the Approval Request.
» type	string	true	none	The type of object, an Approval Request.
» relationshipType	string	true	none	The type of relationship to be created once the approval request is approved.
» approvalRequestType	string	true	none	The type of approval request.
» from	object	false	none	The target associated with the approval request's relationship origin
»» id	string	false	none	none
»» type	string	false	none	none
» to	object	false	none	The target associated with the approval request's relationship target
»» id	string	false	none	none
»» type	string	false	none	none
» approves	object	false	none	The Actor that approves the Approval Request.
»» id	string	false	none	none
»» type	string	false	none	none
» denies	object	false	none	The Actor that denies the Approval Request.
»» id	string	false	none	none
»» type	string	false	none	none
» initiates	object	false	none	The Actor that initiated the Approval Request
»» id	string	false	none	none
»» type	string	false	none	none

Authorization request template

{
  "action": "<approvalTarget>:approvalrequest:deny",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${body.approvalRequestId}",
    "type": "approvalrequest"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case <approvalTarget>:approvalrequest:deny) by using the Authorization Config API.

> Resource Endpoints

List all Resources of type

Code samples

# You can also use wget
curl -X GET /api/v1/resources/{resourceType} \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/resources/{resourceType} HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/resources/{resourceType}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/resources/{resourceType}

Returns all Resources of the specified {resourceType}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
resourceType	path	string	true	The type of Resource.
tenant	path	string	true	Your tenant code.

Example responses

200 Response

[
  {
    "id": "string",
    "type": "string",
    "properties": {}
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
anonymous	[ResourceResponse]	false	none	none
» id	string	true	none	The identifier of the Resource.
» type	string	true	none	The type of Resource.
» properties	object	true	none	Custom defined properties on the node type

Authorization request template

{
  "action": "${params.resourceType}:list",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "type": "${params.resourceType}"
  }
}

Authorization Request

Create a Resource

Code samples

# You can also use wget
curl -X POST /api/v1/resources/{resourceType} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/resources/{resourceType} HTTP/1.1

Content-Type: application/json
Accept: application/json
acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "customAttribute1": "value1",
  "customAttribute2": "value2"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/resources/{resourceType}',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/resources/{resourceType}

Creates a Resource of type {resourceType}. The system will assign a resourceId.

Body parameter

{
  "customAttribute1": "value1",
  "customAttribute2": "value2"
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
resourceType	path	string	true	The type of Resource.
tenant	path	string	true	Your tenant code.
body	body	object	true	An object specifying custom attributes for the Resource. This object must follow the JSON schema defined for the chosen ResourceType.

Example responses

201 Response

{
  "id": "string",
  "type": "string",
  "customAttribute1": "string",
  "customAttribute2": "boolean"
}

Responses

Status	Meaning	Description	Schema
201	Created	none	Inline

Response Schema

Status Code 201

Name	Type	Required	Restrictions	Description
» id	string	true	none	The identifier of the Resource.
» type	string	true	none	The type of the Resource.
» customAttribute	any	false	none	A property defined by the tenant for this type of object.

Authorization request template

{
  "action": "${params.resourceType}:create",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "type": "${params.resourceType}"
  }
}

Authorization Request

Get a Resource

Code samples

# You can also use wget
curl -X GET /api/v1/resources/{resourceType}/{resourceId} \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/resources/{resourceType}/{resourceId} HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/resources/{resourceType}/{resourceId}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/resources/{resourceType}/{resourceId}

Returns the Resource specified by {resourceType} and {resourceId}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
resourceType	path	string	true	The type of Resource.
resourceId	path	string	true	The identifier for the Resource.
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "id": "string",
  "type": "string",
  "customAttribute1": "string",
  "customAttribute2": "boolean"
}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline
404	Not Found	Returns 404 if the Resource is not found	None

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» id	string	true	none	The identifier of the Resource.
» type	string	true	none	The type of the Resource.
» customAttribute	any	false	none	A property defined by the tenant for this type of object.

Authorization request template

{
  "action": "${params.resourceType}:read",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${params.resourceId}",
    "type": "${params.resourceType}"
  }
}

Authorization Request

Create/update a Resource

Code samples

# You can also use wget
curl -X PUT /api/v1/resources/{resourceType}/{resourceId} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

PUT /api/v1/resources/{resourceType}/{resourceId} HTTP/1.1

Content-Type: application/json
Accept: application/json
acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "customAttribute1": "value1",
  "customAttribute2": "value2"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/resources/{resourceType}/{resourceId}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /api/v1/resources/{resourceType}/{resourceId}

Creates or updates the Resource specified by {resourceType} and {resourceId}.

Note: A PUT request overwrites the original object. Be sure to (re-)enter the values for all desired attributes.

Note 2: If the Resource does not exist yet, the {resourceType}:create Policy that will be evaluated. Otherwise the {resourceType}:update Policy will be evaluated

Body parameter

{
  "customAttribute1": "value1",
  "customAttribute2": "value2"
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
resourceType	path	string	true	The type of Resource.
resourceId	path	string	true	The identifier for the Resource.
tenant	path	string	true	Your tenant code.
body	body	object	true	An object specifying custom attributes for the Resource. This object must follow the JSON schema defined for the chosen ResourceType.

Example responses

200 Response

{
  "id": "string",
  "type": "string",
  "customAttribute1": "string",
  "customAttribute2": "boolean"
}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» id	string	true	none	The identifier of the Resource.
» type	string	true	none	The type of the Resource.
» customAttribute	any	false	none	A property defined by the tenant for this type of object.

Authorization request template

{
  "action": "${params.resourceType}:<createOrUpdate>",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${params.resourceId}",
    "type": "${params.resourceType}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.resourceType}:<createOrUpdate>) by using the Authorization Config API.

Delete a Resource

Code samples

# You can also use wget
curl -X DELETE /api/v1/resources/{resourceType}/{resourceId} \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

DELETE /api/v1/resources/{resourceType}/{resourceId} HTTP/1.1

acting-tenant-id: string
tenant-id: string


const headers = {
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/resources/{resourceType}/{resourceId}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /api/v1/resources/{resourceType}/{resourceId}

Removes the Resource specified by {resourceType} and {resourceId}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
resourceType	path	string	true	The type of Resource.
resourceId	path	string	true	The identifier for the Resource.
tenant	path	string	true	Your tenant code.

Responses

Status	Meaning	Description	Schema
200	OK	none	None

Authorization request template

{
  "action": "${params.resourceType}:delete",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${params.resourceId}",
    "type": "${params.resourceType}"
  }
}

Authorization Request

List all Relationships

Code samples

# You can also use wget
curl -X GET /api/v1/resources/{resourceType}/{resourceId}/relationships \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

GET /api/v1/resources/{resourceType}/{resourceId}/relationships HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/resources/{resourceType}/{resourceId}/relationships',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /api/v1/resources/{resourceType}/{resourceId}/relationships

Returns all Relationships of the Resource specified by {resourceType} and {resourceId}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
resourceType	path	string	true	The type of Resource.
resourceId	path	string	true	The identifier for the Resource.
relationship-types	query	string	false	Optional comma-separated list of RelationshipTypes to filter on.
direction	query	string	false	Optional direction (`from` or `to`) of the Relationship with respect to the Resource specified by {resourceType} and {resourceId}.
signed	query	boolean	false	Optional signing of Relationships. If true, the response will contain signed Relationships. The default value is false; the response contains human-readable objects.
all	query	boolean	false	Optional inclusion of reserved RelationshipTypes. If true, the response will include the RelationshipTypes predefined by Scaled Access. The default value is false.
tenant	path	string	true	Your tenant code.

Enumerated Values

Parameter	Value
direction	from
direction	to

Example responses

200 Response

[
  {
    "id": "string",
    "relationshipType": "string",
    "from": {
      "id": "string",
      "type": "string",
      "properties": {}
    },
    "to": {
      "id": "string",
      "type": "string",
      "properties": {}
    },
    "properties": {}
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
anonymous	[RelationshipDetailResponse]	false	none	none
» id	string	true	none	The identifier for the Relationship.
» relationshipType	string	true	none	The type of Relationship between the `from` and `to` Actor(s)/Resource(s).
» from	NodeDetailResponse	true	none	none
»» id	string	true	none	The identifier of the Actor/Resource.
»» type	string	true	none	The `actorType` or `resourceType` of the Actor/Resource.
»» properties	object	true	none	Custom defined properties on the node type
» to	NodeDetailResponse	true	none	none
» properties	object	false	none	The custom properties of the Relationship.

Authorization request template

{
  "action": "${params.resourceType}:relationships:list",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${params.resourceId}",
    "type": "${params.resourceType}",
    "relationshipTypes": "${query[\"relationship-types\"]}",
    "direction": "${query[\"direction\"]}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.resourceType}:relationships:list) by using the Authorization Config API.

Create a Relationship

Code samples

# You can also use wget
curl -X POST /api/v1/resources/{resourceType}/{resourceId}/relationships \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

POST /api/v1/resources/{resourceType}/{resourceId}/relationships HTTP/1.1

Content-Type: application/json
Accept: application/json
acting-tenant-id: string
tenant-id: string

const inputBody = '{
  "relationshipType": "string",
  "to": {
    "id": "string",
    "type": "string"
  },
  "properties": {
    "customAttribute1": "string",
    "customAttribute2": true
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/resources/{resourceType}/{resourceId}/relationships',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /api/v1/resources/{resourceType}/{resourceId}/relationships

Creates a Relationship for the Resource specified by {resourceType} and {resourceId}. The target must be specified with either the from or to body parameter.

Body parameter

{
  "relationshipType": "string",
  "to": {
    "id": "string",
    "type": "string"
  },
  "properties": {
    "customAttribute1": "string",
    "customAttribute2": true
  }
}

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
resourceType	path	string	true	The type of Resource.
resourceId	path	string	true	The identifier for the Resource.
tenant	path	string	true	Your tenant code.
body	body	object	true	none
» relationshipType	body	string	true	The type of relationship.
» to	body	object	true	The target Actor/Resource in the Relationship.
» properties	body	object	false	The custom properties as defined in the relationship type.

Example responses

200 Response

{
  "id": "string",
  "relationshipType": "string",
  "from": {
    "id": "string",
    "type": "string",
    "properties": {}
  },
  "to": {
    "id": "string",
    "type": "string",
    "properties": {}
  },
  "properties": {}
}

Responses

Status	Meaning	Description	Schema
200	OK	none	RelationshipDetailResponse

Authorization request template

{
  "action": "${params.resourceType}:${body.relationshipType}:${body.to.type}:create",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${params.resourceId}",
      "type": "${params.resourceType}"
    },
    "to": {
      "id": "${body.to.id}",
      "type": "${body.to.type}"
    },
    "relationshipType": "${body.relationshipType}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.resourceType}:${body.relationshipType}:${body.to.type}:create) by using the Authorization Config API.

Delete a Relationship

Code samples

# You can also use wget
curl -X DELETE /api/v1/resources/{resourceType}/{resourceId}/relationships/{relationshipId} \
  -H 'Accept: application/json' \
  -H 'acting-tenant-id: string' \
  -H 'tenant-id: string' \
  -H 'Authorization: Bearer {access-token}'

DELETE /api/v1/resources/{resourceType}/{resourceId}/relationships/{relationshipId} HTTP/1.1

Accept: application/json
acting-tenant-id: string
tenant-id: string


const headers = {
  'Accept':'application/json',
  'acting-tenant-id':'string',
  'tenant-id':'string',
  'Authorization':'Bearer {access-token}'
};

fetch('/api/v1/resources/{resourceType}/{resourceId}/relationships/{relationshipId}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /api/v1/resources/{resourceType}/{resourceId}/relationships/{relationshipId}

Removes the Relationship specified by {relationshipId}, of the Resource specified by {resourceType} and {resourceId}.

Parameters

Name	In	Type	Required	Description
acting-tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter
tenant-id	header	string	false	Tenant code. Used when not passing the tenant code in the URL path parameter and not passing the acting tenant id in header
resourceId	path	string	true	The identifier for the Resource.
resourceType	path	string	true	The type of Resource.
relationshipId	path	string	true	The identifier for the Relationship.
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "id": "string",
  "relationshipType": "string",
  "from": {
    "id": "string",
    "type": "string",
    "properties": {}
  },
  "to": {
    "id": "string",
    "type": "string",
    "properties": {}
  },
  "properties": {}
}

Responses

Status	Meaning	Description	Schema
200	OK	none	RelationshipDetailResponse

Authorization request template

{
  "action": "${params.resourceType}:<relationshipType>:<targetType>:delete",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${params.resourceId}",
      "type": "${params

Welcome

Onboarding

Getting started with Relationship Management in OneWelcome

OneWelcome account details

How to access the Config API?

How to access the Management APIs?

Integration with Auth0

How to add a custom Relationship claim?

Auth0 setup

Step 1. Create a Custom Action

Step 2. Use the Custom Action in a Login Flow

Obtaining and using an enriched access token

Step 3. Request an Auth0 access token

Step 4. Make access decisions based on Relationships

Testing token enrichment in Postman

Auth0 setup

Step 0. Prepare the client application for Postman callbacks

Step 1-3. Add the Auth0 Custom Action

Obtaining an enriched access token in Postman

Step 4. Request an Auth0 access token

Integration with Okta

How to set up the Okta inline hook?

Okta setup

Step 1. Create an inline hook

Step 2. Activate the inline hook

Obtaining and using an enriched access token

Step 3. Request an Okta access token

Step 4. Make access decisions based on Relationships

Testing token enrichment in Postman

Okta setup

Step 1. Create a demo application

Step 2. Assign the demo application to a test user

Obtaining an enriched access token in Postman

Step 3. Request an Okta access token

Step 4. Check the enriched token

Integration with OneWelcome

How to set up the OneWelcome Mobile Identity Web Hook?

Mobile Identity setup

Step 1. Create a Web Hook

Step 2. Activate the Web Hook

Obtaining and using an enriched access token

Step 3. Request a OneWelcome access token

Step 4. Make access decisions based on Relationships

Integration with Akamai Identity Cloud

About the PolicyGate API

About OAuth 2.0

About OIDC 1.0

Customization of the user journey

How to get started?

Externalized Authorization

Overview and Concepts

About Externalized Authorization

Externalized Authorization with OneWelcome

Configuration of Policies: Config API

Information Model

Objects and Attributes

Policy Name Attribute

The Rego Attribute and the Graphical Representation

Executing Policies: Authorization API

Information Model

Endpoints Overview

Authorization Config API

List all Policies

Parameters

Responses

Get a Policy

Parameters

Responses

Create/update Policy

Parameters

Responses

Delete a Policy

Parameters

Responses

Schemas

PolicyRecordResponse

GraphicalPolicyNodeInput

GraphicalPolicyLinkInput

GraphicalPolicyInput

UpdatePolicyDataRequest