Welcome

The Scaled Access 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 Scaled Access

Scaled Access account details

For each new Scaled Access 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 Scaled Access Config API. Access to this API is granted through an invitation from Scaled Access. Scaled Access 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.
The obtained access token must be stored safely, i.e. not in a browser.
Place the access token in the Authorization Header of subsequent requests to the Config 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 the Authorization API or one of our trusted authorization servers, such as Auth0. 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@scaledaccess.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 Scaled Access 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. Scaled Access provides an extension to Auth0 that allows 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 Rule in the Auth0 dashboard and specify which scope you wish to add. More integration methods will be added in the near future.

How to add a custom Relationship claim?

Auth0 Setup

Step 1. Create an API

Create a new API in Auth0. The identifier should be the same value as the audience you provided Scaled Access when we created your tenant.
Go to the Permissions tab and add a Permission (Scope) with value pg:tenant:admin. Fill in Description to your liking.

Step 2. Create an Application

Go to Applications and click Create application.
Select Machine to Machine Applications.
Choose the API you created in the previous step.
Select the pg:tenant:admin scope and click Authorize.

Step 3. Add the Auth0 Rule

function scaledAccessAddRelationshipsClaim(user, context, callback) {
    const fetch = require("node-fetch");
    const { URLSearchParams } = require('url');

    const getM2mToken = () => {
        if (global.scaledAccessM2mToken && global.scaledAccessM2mTokenExpiryInMillis > new Date().getTime() + 60000) {
            return Promise.resolve(global.scaledAccessM2mToken);
        } else {
            const tokenUrl = `https://${context.request.hostname}/oauth/token`;
            return fetch(tokenUrl, {
                method: 'POST',
                body: new URLSearchParams({
                    grant_type: 'client_credentials',
                    client_id: configuration.SCALED_ACCESS_CLIENTID,
                    client_secret: configuration.SCALED_ACCESS_CLIENTSECRET,
                    audience: configuration.SCALED_ACCESS_AUDIENCE,
                    scope: 'pg:tenant:admin'
                })
            })
                .then(response => {
                    if (!response.ok) {
                        return response.text().then((error) => {
                            console.error("Failed to obtain m2m token from " + tokenUrl);
                            throw Error(error);
                        });
                    } else {
                        return response.json();
                    }
                })
                .then(({ access_token, expires_in }) => {
                    global.scaledAccessM2mToken = access_token;
                    global.scaledAccessM2mTokenExpiryInMillis = new Date().getTime() + expires_in * 1000;
                    return access_token;
                });
        }
    };

    const callRelationshipManagementApi = async (accessToken, path) => {
        const url = `${configuration.SCALED_ACCESS_BASEURL}/${configuration.SCALED_ACCESS_TENANT}/${path}`;
        return fetch(url, {
            method: 'GET',
            headers: {
                "Authorization": "Bearer " + accessToken,
                "Content-Type": "application/json"
            }
        })
            .then(async response => {
                if (response.status === 404) {
                    return [];
                } else if (!response.ok) {
                    return response.text().then((error) => {
                        console.error("Failed to call relationship management API", url);
                        throw Error(error);
                    });
                } else {
                    return response.json();
                }
            });
    };

    const getRelationships = (accessToken) => {
        return callRelationshipManagementApi(accessToken, `actors/user/${user.user_id}/relationships`);
    };

    const addClaimToToken = (apiResponse) => {
        const claimName = configuration.SCALED_ACCESS_CUSTOMCLAIM || `https://scaledaccess.com/relationships`;
        context.accessToken[claimName] = apiResponse.map(relationship => ({
            relationshipType: relationship.relationshipType,
            to: relationship.to
        }));
    };

    getM2mToken()
        .then(getRelationships)
        .then(addClaimToToken)
        .then(() => {
            callback(null, user, context);
        })
        .catch(err => {
            console.error(err);
            console.log("Using configuration: ", JSON.stringify(configuration));
            callback(null, user, context); // fail gracefully, token just won't have extra claim
        });
}

In the Auth0 dashboard, go to (Auth pipelines >) Rules > Create Rule.
In the next screen, choose Empty Rule.
Choose a name for your rule.
Copy the script on the right in the online editor and paste it on the Create Rule page.
Click Save Changes.
Click Back to Rules.
Enter the Key and Value for the following rule settings (click + ADD to add multiple entries):

Key	Value
`SCALED_ACCESS_CLIENTID`	The Client ID of the Machine-to-machine application created earlier.
`SCALED_ACCESS_CLIENTSECRET`	The Client Secret of the Machine-to-machine application.
`SCALED_ACCESS_BASEURL`	The base URL for the Relationship Management API, e.g. https://api.int.scaledaccess.com/privategroups-v2.
`SCALED_ACCESS_TENANT`	Your tenant code provided by Scaled Access (see Scaled Access account details).
`SCALED_ACCESS_CUSTOMCLAIM`	An Auth0 Namespaced Custom Claim of your choice. Defaults to `https://scaledaccess.com/relationships`. The custom claim must be a URL. Non-URL claims will be deleted from the access token.
`SCALED_ACCESS_AUDIENCE`	The identifier of the API you created in Step 1.

Obtaining and using an enriched access token

Step 4. Request an Auth0 access token

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

Step 5. 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 Rule

Follow the instructions in step 1-3 of How to add a custom Relationship claim to create the Auth0 API, Application, and Rule.

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 Akamai Identity Cloud

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

About the PolicyGate API

The Scaled Access 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 Scaled Access 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 allows 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 Scaled Access 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 Scaled Access. 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 Scaled Access 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@scaledaccess.com to access detailed information on how to integrate Akamai Identity Cloud with the PolicyGate API.

Externalized Authorization

The Scaled Access Externalized Authorization feature allows 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, ensures security, and allows for scalability.

Externalized Authorization with Scaled Access

Scaled Access 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 allows Scaled Access customers, called tenants, to define Policies that can be used by the Authorization API to make authorization decisions for the other Scaled Access 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 Scaled Access 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 Scaled Access 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 node, 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 node for each RelationshipType you wish to include. The amount of starting nodes is unlimited.	There are two User starting nodes 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 Scaled Access 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

Authorization Config API

List all Policies

Code samples

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

GET /tenants/{tenant}/policies HTTP/1.1


const headers = {
  'Authorization':'Bearer {access-token}'
};

fetch('/tenants/{tenant}/policies',
{
  method: 'GET',

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

GET /tenants/{tenant}/policies

Lists all defined Policies.

Responses

Status	Meaning	Description	Schema
200	OK	none	None

Get a Policy

Code samples

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

GET /tenants/{tenant}/policies/{policyName} HTTP/1.1


const headers = {
  'Authorization':'Bearer {access-token}'
};

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

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

GET /tenants/{tenant}/policies/{policyName}

Returns a specific Policy.

Parameters

Name	In	Type	Required	Description
policyName	path	string	true	The identifier for the Policy.

Responses

Status	Meaning	Description	Schema
200	OK	none	None

Create/update Policy

Code samples

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

PUT /tenants/{tenant}/policies/{policyName} HTTP/1.1

Content-Type: application/json

const inputBody = '{
  "rego": "string",
  "graph": {}
}';
const headers = {
  'Content-Type':'application/json',
  'Authorization':'Bearer {access-token}'
};

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

PUT /tenants/{tenant}/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 attributes.

Body parameter

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

Parameters

Name	In	Type	Required	Description
policyName	path	string	true	The identifier for the Policy.
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 /tenants/{tenant}/policies/{policyName} \
  -H 'Authorization: Bearer {access-token}'

DELETE /tenants/{tenant}/policies/{policyName} HTTP/1.1


const headers = {
  'Authorization':'Bearer {access-token}'
};

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

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

DELETE /tenants/{tenant}/policies/{policyName}

Removes the Policy specified by {policyName}.

Parameters

Name	In	Type	Required	Description
policyName	path	string	true	The identifier for the Policy.

Responses

Status	Meaning	Description	Schema
200	OK	none	None

Schemas

UpdatePolicyDataRequest

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

Name	Type	Required	Restrictions	Description
rego	string	false	none	The raw Rego policy data. If not provided, the graph field must be provided.
graph	object	false	none	The graphical representation of the Rego policy. If provided, this will take precedence over the rego field. The graphical representation will be converted to a Rego policy. If not provided, the rego field must be provided.

Authorization API

Authorize request

Code samples

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

POST https://api.int.scaledaccess.com/authz/{tenant} HTTP/1.1
Host: api.int.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.int.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.
» 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

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» outcome	string	false	none	The outcome of the authorization decision, either a string (allow/deny) or an object as specified by the policy.

anyOf

Name	Type	Required	Restrictions	Description
»» anonymous	any	false	none	none

Name	Type	Required	Restrictions	Description
»» anonymous	object	false	none	none

continued

Name	Type	Required	Restrictions	Description
» 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.

Enumerated Values

Property	Value
anonymous	allow
anonymous	deny

The Scaled Access Consent Enforcement feature allows 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 (eg. 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.

Scaled Access offers help with this so-called Consent Enforcement by providing an API-based system to:

Config API: Define customized consents.
Consent Management API: Register user consents and log each action with regard to these consents.
Authorization API: Take user consents into account to make authorization decisions.

Information Model

The Config API allows Scaled Access customers, called tenants, to set up consent definitions (e.g. general terms and conditions, policy for newsletter). Each definition has one or more versions, which contain one or more documents.

Objects and Attributes

Object	Example	Description
ConsentDefinition	terms-and-conditions	The ConsentDefinition is a master data object grouping all information about one logical consent. Each ConsentDefinition has one or more ConsentVersions.
ConsentVersion	2.0	The ConsentVersion contains all information about a specific version of the consent (e.g. opt-in configuration). Each ConsentVersion has one or more ConsentDocuments.
ConsentDocument	terms-conditions-2.0.1-EN	The ConsentDocument represents the specific consent to which a user agrees, i.e. the consent with a specific document version in a specific language. The moment in time the ConstentDocument can obtain the "effective" status is specified with the `effectiveDate`.

The optInConfig Attribute

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 Attribute

To regulate the transition to a new ConsentVersion, an endOfLife can be added to the previous ConsentVersion. This attribute indicates when the transition starts (startDate) and at what moment in time the previous version is 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 (see "user B" in the example image below).

Custom Attributes

The Scaled Access customer can define additional attributes for ConsentDefinition, ConsentVersion, and/or ConsentDocument. If set as required, the attribute will have to be provided for every object of that specific type.

At the moment, adding custom attributes can only be done by a Scaled Access developer. Please contact us via support@scaledaccess.com.

Most consent documents end up getting minor and/or major updates, which result respectively in new document and new consent versions. To determine which documents are currently valid and which document should be offered to a (new) user, a set of logical rules is followed.

Effective, Active, and Valid Documents

All ConsentDocuments have the required attribute effectiveDate which indicates the first moment in time at which the document can be offered to users, i.e. when they are "effective".

The "active" document of a consent is the document that should currently be offered to (new) users. For each ConsentDefinition, there can only be one active document per language. The active document is always determined in real-time, based on a ConsentDefinition's name and the desired language.

Although the active document is the most current document version, a user's consent to an older version might still be sufficient, i.e. the document is "valid".

Status	Requirements
effective	The `effectiveDate` lies in the past. The ConsentDocument belongs to a ConsentVersion of which, if it has an endOfLife associated with it, the `endDate` is not reached yet.
active	The ConsentDocument is effective. For a specific `language`, the `effectiveDate` is the most recent of all ConsentDocuments (accross multiple ConsentVersions).
valid	The ConsentDocument is effective. At least one of the following is true: The ConsentDocument is active. The active ConsentDocument is located in the same ConsentVersion (i.e. the active document is only a minor update). The active ConsentDocument is located in another ConsentVersion, but the grace period for the specific user is still ongoing (i.e. during the transition to a new ConsentVersion).

Once ConsentDocuments reach their effectiveDate, they can no longer be modified. A new ConsentDocument must be created to apply minor (e.g. formulation) or major (content) changes.

Update	User action required?	Location of ConsentDocument	Description
minor	No, the previous version stays valid.	ConsentDocuments with minor differences should be located in the same ConsentVersion.	The ConsentDocument for which the user already gave their consent, is still valid. The user may continue using the product.
major	Yes, the user must consent to the new ConsentDocument.	The new ConsentDocument must be located in a new ConsentVersion.	The transition to a new ConsentVersion makes use of a grace period. During the grace period: The ConsentDocument for which the user already gave their consent, is still valid. The user may continue using the product, but should be reminded of the need to renew their consent. After the grace period: The user's access to the product will be denied until the user agrees with the new ConsentDocument. The grace period is defined in the endOfLife of the ConsentVersion to which the previously accepted 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.

Information Model

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

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

A ConsentDocument is uniquely identified by four attributes: name, version, documentVersion, and language.

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`	policy	Jane Doe	Token requested for double opt-in method.
`2020-01-10T04:55:05Z`	policy	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.

Authorization Rules

Users can only make requests about their own UserConsents, whereas tenants have access to the UserConsents of all their users. Both parties can request the currently active ConsentDocument for a specific ConsentDefinition (name) and language.

Access Management with User Consents: Authorization API

Policies

To be in compliance with the GDPR rules, user consents do not only need to be registered, they also need to be part of the polices that are used to determine access rights. See the feature Externalized Authorization for more information on how to define and implement these policies for your application.

Endpoints Overview

List all ConsentDefinitions

Code samples

# You can also use wget
curl -X GET /tenants/{tenant}/consent-definitions \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /tenants/{tenant}/consent-definitions HTTP/1.1

Accept: application/json


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

fetch('/tenants/{tenant}/consent-definitions',
{
  method: 'GET',

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

GET /tenants/{tenant}/consent-definitions

Lists all defined ConsentDefinitions.

Parameters

Name	In	Type	Required	Description
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "resources": [
    "string"
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ConsentDefinitionsResponse

Get ConsentDefinition

Code samples

# You can also use wget
curl -X GET /tenants/{tenant}/consent-definitions/{name} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /tenants/{tenant}/consent-definitions/{name} HTTP/1.1

Accept: application/json


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

fetch('/tenants/{tenant}/consent-definitions/{name}',
{
  method: 'GET',

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

GET /tenants/{tenant}/consent-definitions/{name}

Returns the ConsentDefinition specified by {name}.

Parameters

Name	In	Type	Required	Description
name	path	string	true	The identifier for the ConsentDefinition.
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "resources": [
    "versions"
  ],
  "config": {
    "name": "string"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ConsentDefinitionResponse

Create/update ConsentDefinition

Code samples

# You can also use wget
curl -X PUT /tenants/{tenant}/consent-definitions/{name} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

PUT /tenants/{tenant}/consent-definitions/{name} HTTP/1.1

Content-Type: application/json
Accept: application/json

const inputBody = '{}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/tenants/{tenant}/consent-definitions/{name}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /tenants/{tenant}/consent-definitions/{name}

Creates or updates the ConsentDefinition specified by {name}.

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

Body parameter

{}

Parameters

Name	In	Type	Required	Description
name	path	string	true	The identifier for the ConsentDefinition.
tenant	path	string	true	Your tenant code.
body	body	ConsentDefinitionRequest	true	none

Example responses

200 Response

{}

Responses

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

List all ConsentVersions

Code samples

# You can also use wget
curl -X GET /tenants/{tenant}/consent-definitions/{name}/versions \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /tenants/{tenant}/consent-definitions/{name}/versions HTTP/1.1

Accept: application/json


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

fetch('/tenants/{tenant}/consent-definitions/{name}/versions',
{
  method: 'GET',

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

GET /tenants/{tenant}/consent-definitions/{name}/versions

Lists all ConsentVersions in ConsentDocument {name}.

Parameters

Name	In	Type	Required	Description
name	path	string	true	The identifier for the ConsentDefinition.
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "resources": [
    "string"
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ConsentVersionsResponse

Get ConsentVersion

Code samples

# You can also use wget
curl -X GET /tenants/{tenant}/consent-definitions/{name}/versions/{version} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /tenants/{tenant}/consent-definitions/{name}/versions/{version} HTTP/1.1

Accept: application/json


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

fetch('/tenants/{tenant}/consent-definitions/{name}/versions/{version}',
{
  method: 'GET',

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

GET /tenants/{tenant}/consent-definitions/{name}/versions/{version}

Returns the ConsentVersion specified by {version} in ConsentDefinition {name}.

Parameters

Name	In	Type	Required	Description
name	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion..
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "resources": [
    "documents",
    "end-of-life"
  ],
  "config": {
    "version": "string",
    "endOfLife": {
      "startDate": "string",
      "endDate": "string",
      "gracePeriod": "string"
    },
    "optInConfig": [
      {
        "type": "direct"
      }
    ]
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ConsentVersionResponse

Create/update ConsentVersion

Code samples

# You can also use wget
curl -X PUT /tenants/{tenant}/consent-definitions/{name}/versions/{version} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

PUT /tenants/{tenant}/consent-definitions/{name}/versions/{version} HTTP/1.1

Content-Type: application/json
Accept: application/json

const inputBody = '{
  "optInConfig": {
    "type": "direct"
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

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

PUT /tenants/{tenant}/consent-definitions/{name}/versions/{version}

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

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

Body parameter

{
  "optInConfig": {
    "type": "direct"
  }
}

Parameters

Name	In	Type	Required	Description
name	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion..
tenant	path	string	true	Your tenant code.
body	body	ConsentVersionRequest	true	none

Example responses

200 Response

{}

Responses

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

Get endOfLife of ConsentVersion

Code samples

# You can also use wget
curl -X GET /tenants/{tenant}/consent-definitions/{name}/versions/{version}/end-of-life \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /tenants/{tenant}/consent-definitions/{name}/versions/{version}/end-of-life HTTP/1.1

Accept: application/json


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

fetch('/tenants/{tenant}/consent-definitions/{name}/versions/{version}/end-of-life',
{
  method: 'GET',

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

GET /tenants/{tenant}/consent-definitions/{name}/versions/{version}/end-of-life

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

Parameters

Name	In	Type	Required	Description
name	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion..
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "config": {
    "startDate": "string",
    "endDate": "string",
    "gracePeriod": "string"
  }
}

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

Create/update EndOfLife of ConsentVersion

Code samples

# You can also use wget
curl -X PUT /tenants/{tenant}/consent-definitions/{name}/versions/{version}/end-of-life \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

PUT /tenants/{tenant}/consent-definitions/{name}/versions/{version}/end-of-life HTTP/1.1

Content-Type: application/json
Accept: application/json

const inputBody = '{
  "startDate": "string",
  "endDate": "string",
  "gracePeriod": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

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

PUT /tenants/{tenant}/consent-definitions/{name}/versions/{version}/end-of-life

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

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

Body parameter

{
  "startDate": "string",
  "endDate": "string",
  "gracePeriod": "string"
}

Parameters

Name	In	Type	Required	Description
name	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion..
tenant	path	string	true	Your tenant code.
body	body	EndOfLifeRequest	true	none

Example responses

200 Response

{}

Responses

Status	Meaning	Description	Schema
200	OK	none	EmptyResponse

List all ConsentDocument languages

Code samples

# You can also use wget
curl -X GET /tenants/{tenant}/consent-definitions/{name}/versions/{version}/documents \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /tenants/{tenant}/consent-definitions/{name}/versions/{version}/documents HTTP/1.1

Accept: application/json


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

fetch('/tenants/{tenant}/consent-definitions/{name}/versions/{version}/documents',
{
  method: 'GET',

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

GET /tenants/{tenant}/consent-definitions/{name}/versions/{version}/documents

Lists all languages for which ConsentDocuments exist in ConsentVersion {version} of ConsentDocument {name}.

Parameters

Name	In	Type	Required	Description
name	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion..
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "resources": [
    "string"
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ConsentDocumentsLanguagesResponse

List all ConsentDocuments for one language

Code samples

# You can also use wget
curl -X GET /tenants/{tenant}/consent-definitions/{name}/versions/{version}/documents/{language} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /tenants/{tenant}/consent-definitions/{name}/versions/{version}/documents/{language} HTTP/1.1

Accept: application/json


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

fetch('/tenants/{tenant}/consent-definitions/{name}/versions/{version}/documents/{language}',
{
  method: 'GET',

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

GET /tenants/{tenant}/consent-definitions/{name}/versions/{version}/documents/{language}

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

Parameters

Name	In	Type	Required	Description
name	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion..
language	path	string	true	The `language` identifier for the ConsentDocument.
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "resources": [
    "string"
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ConsentDocumentsResponse

Get ConsentDocument

Code samples

# You can also use wget
curl -X GET /tenants/{tenant}/consent-definitions/{name}/versions/{version}/documents/{language}/{documentVersion} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /tenants/{tenant}/consent-definitions/{name}/versions/{version}/documents/{language}/{documentVersion} HTTP/1.1

Accept: application/json


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

fetch('/tenants/{tenant}/consent-definitions/{name}/versions/{version}/documents/{language}/{documentVersion}',
{
  method: 'GET',

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

GET /tenants/{tenant}/consent-definitions/{name}/versions/{version}/documents/{language}/{documentVersion}

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

Parameters

Name	In	Type	Required	Description
name	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion..
language	path	string	true	The `language` identifier for the ConsentDocument.
documentVersion	path	string	true	The `documentVersion` identifier for the ConsentDocument.
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "config": {
    "version": "string",
    "language": "string",
    "effectiveDate": "2019-12-21T10:00:00.000Z"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ConsentDocumentResponse

Create/update ConsentDocument

Code samples

# You can also use wget
curl -X PUT /tenants/{tenant}/consent-definitions/{name}/versions/{version}/documents/{language}/{documentVersion} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

PUT /tenants/{tenant}/consent-definitions/{name}/versions/{version}/documents/{language}/{documentVersion} HTTP/1.1

Content-Type: application/json
Accept: application/json

const inputBody = '{
  "effectiveDate": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

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

PUT /tenants/{tenant}/consent-definitions/{name}/versions/{version}/documents/{language}/{documentVersion}

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

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

Body parameter

{
  "effectiveDate": "string"
}

Parameters

Name	In	Type	Required	Description
name	path	string	true	The identifier for the ConsentDefinition.
version	path	string	true	The identifier for the ConsentVersion..
language	path	string	true	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.
documentVersion	path	string	true	An identifier for the ConsentDocument. The ConsentDocument is uniquely identified within the context of the ConsentVersion by the combination of `language` and `documentVersion`.
tenant	path	string	true	Your tenant code.
body	body	ConsentDocumentRequest	true	none

Example responses

200 Response

{}

Responses

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

ConsentDefinitionsResponse

{
  "resources": [
    "string"
  ]
}

Name	Type	Required	Restrictions	Description
resources	[string]	true	none	A list of the ConsentDefinitions (`name`) defined by the tenant.

ConsentDefinition

{
  "name": "string"
}

Name	Type	Required	Restrictions	Description
name	string	true	none	The identifier for the ConsentDefinition.

ConsentDefinitionResponse

{
  "resources": [
    "versions"
  ],
  "config": {
    "name": "string"
  }
}

Name	Type	Required	Restrictions	Description
resources	[string]	true	none	none
config	ConsentDefinition	true	none	none

ConsentDefinitionRequest

{}

None

EmptyResponse

{}

None

ConsentVersionsResponse

{
  "resources": [
    "string"
  ]
}

Name	Type	Required	Restrictions	Description
resources	[string]	true	none	A list of the ConsentVersions (`version`) belonging to the requested ConsentDefinition.

EndOfLifeRequest

{
  "startDate": "string",
  "endDate": "string",
  "gracePeriod": "string"
}

Name	Type	Required	Restrictions	Description
startDate	string	true	none	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	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 period 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 will never extend passed the `endDate`.

ConsentVersion

{
  "version": "string",
  "endOfLife": {
    "startDate": "string",
    "endDate": "string",
    "gracePeriod": "string"
  },
  "optInConfig": [
    {
      "type": "direct"
    }
  ]
}

Name	Type	Required	Restrictions	Description
version	string	true	none	The identifier for the ConsentVersion.
endOfLife	EndOfLifeRequest	false	none	none
optInConfig	[object]	true	none	none
» type	string	true	none	none

ConsentVersionResponse

{
  "resources": [
    "documents",
    "end-of-life"
  ],
  "config": {
    "version": "string",
    "endOfLife": {
      "startDate": "string",
      "endDate": "string",
      "gracePeriod": "string"
    },
    "optInConfig": [
      {
        "type": "direct"
      }
    ]
  }
}

Name	Type	Required	Restrictions	Description
resources	[string]	true	none	none
config	ConsentVersion	true	none	none

OptInConfigRequest

{
  "type": "direct"
}

Name	Type	Required	Restrictions	Description
type	string	true	none	The opt-in method. This value must be set to `direct`.

ConsentVersionRequest

{
  "optInConfig": {
    "type": "direct"
  }
}

Name	Type	Required	Restrictions	Description
optInConfig	OptInConfigRequest	true	none	none

ConsentVersionEndOfLifeResponse

{
  "config": {
    "startDate": "string",
    "endDate": "string",
    "gracePeriod": "string"
  }
}

Name	Type	Required	Restrictions	Description
config	EndOfLifeRequest	true	none	none

ConsentDocumentsLanguagesResponse

{
  "resources": [
    "string"
  ]
}

Name	Type	Required	Restrictions	Description
resources	[string]	true	none	A list of the languages (`language`) for which ConsentDocuments exist that belong to the requested ConsentVersion.

ConsentDocumentsResponse

{
  "resources": [
    "string"
  ]
}

Name	Type	Required	Restrictions	Description
resources	[string]	true	none	A list of the ConsentDocuments (`documentVersion`) in the requested `language` and belonging to the requested ConsentVersion.

ConsentDocument

{
  "version": "string",
  "language": "string",
  "effectiveDate": "2019-12-21T10:00:00.000Z"
}

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	true	none	The moment in time at which the ConsentDocument can become effective and might replace a previous version (ISO-8601 dateTime format).

ConsentDocumentResponse

{
  "config": {
    "version": "string",
    "language": "string",
    "effectiveDate": "2019-12-21T10:00:00.000Z"
  }
}

Name	Type	Required	Restrictions	Description
config	ConsentDocument	true	none	none

ConsentDocumentRequest

{
  "effectiveDate": "string"
}

Name	Type	Required	Restrictions	Description
effectiveDate	string	true	none	A datetime (ISO-8601 format) indicating the moment in time at which this specific document can become effective and might replace a previous version. The `effectivedate` cannot be set in the past.

Get the active ConsentDocument

Code samples

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

GET /{tenant}/consents/active?name=string&language=string HTTP/1.1

Accept: application/json


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

fetch('/{tenant}/consents/active?name=string&language=string',
{
  method: 'GET',

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

GET /{tenant}/consents/active

Returns information about the currently active name version and document given the name name and document language. Active version and document are determined by taking the document with the latest effectiveDate that is before now, beloning to a version that is not end of life.

Parameters

Name	In	Type	Required	Description
tenant	path	string	true	Your tenant code.
name	query	string	true	The `name` of the ConsentDefinition for which to find the active ConsentDocument.
language	query	string	true	The `language` for which to find the active ConsentDocument.

Example responses

200 Response

{
  "name": "string",
  "version": "string",
  "document": {
    "version": "string",
    "language": "string"
  },
  "status": "string",
  "gracePeriodEnds": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ConsentResponse

List my UserConsents

Code samples

# You can also use wget
curl -X GET /{tenant}/consents/me \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /{tenant}/consents/me HTTP/1.1

Accept: application/json


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

fetch('/{tenant}/consents/me',
{
  method: 'GET',

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

GET /{tenant}/consents/me

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

Parameters

Name	In	Type	Required	Description
tenant	path	string	true	none
filter	query	array	true	none

Example responses

200 Response

{
  "consents": [
    {
      "id": "string",
      "userId": "string",
      "consent": {
        "name": "string",
        "version": "string",
        "document": {
          "version": "string",
          "language": "string"
        },
        "status": "string",
        "gracePeriodEnds": "string"
      },
      "metaData": {
        "created": 0,
        "lastUpdate": 0
      },
      "client": "string"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ConsentListResponse

Register my UserConsent

Code samples

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

POST /{tenant}/consents/me HTTP/1.1

Content-Type: application/json
Accept: application/json

const inputBody = '{
  "name": "string",
  "version": "string",
  "document": {
    "language": "string",
    "version": "string"
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

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

POST /{tenant}/consents/me

Registers a new UserConsent for the user authenticated by the user access token.

Body parameter

{
  "name": "string",
  "version": "string",
  "document": {
    "language": "string",
    "version": "string"
  }
}

Parameters

Name	In	Type	Required	Description
tenant	path	string	true	none
body	body	RegisterConsentRequest	true	none

Example responses

201 Response

{
  "name": "string",
  "version": "string",
  "document": {
    "version": "string",
    "language": "string"
  },
  "status": "string",
  "gracePeriodEnds": "string"
}

Responses

Status	Meaning	Description	Schema
201	Created	none	ConsentResponse

Withdraw my UserConsent

Code samples

# You can also use wget
curl -X DELETE /{tenant}/consents/me?id=string&delete=string \
  -H 'Authorization: Bearer {access-token}'

DELETE /{tenant}/consents/me?id=string&delete=string HTTP/1.1


const headers = {
  'Authorization':'Bearer {access-token}'
};

fetch('/{tenant}/consents/me?id=string&delete=string',
{
  method: 'DELETE',

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

DELETE /{tenant}/consents/me

Removes a UserConsent from the user authenticated by the user access token. An audit trail is kept.

Parameters

Name	In	Type	Required	Description
tenant	path	string	true	none
id	query	string	true	The identifier for the UserConsent. The `id` can be found in the response of the List my UserConsents endpoint.
delete	query	string	true	none

Responses

Status	Meaning	Description	Schema
200	OK	none	None

List all UserConsents

Code samples

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

GET /{tenant}/consents/{userId} HTTP/1.1

Accept: application/json


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

fetch('/{tenant}/consents/{userId}',
{
  method: 'GET',

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

GET /{tenant}/consents/{userId}

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

Parameters

Name	In	Type	Required	Description
tenant	path	string	true	none
userId	path	string	true	none
filter	query	array	true	none

Example responses

200 Response

{
  "consents": [
    {
      "id": "string",
      "userId": "string",
      "consent": {
        "name": "string",
        "version": "string",
        "document": {
          "version": "string",
          "language": "string"
        },
        "status": "string",
        "gracePeriodEnds": "string"
      },
      "metaData": {
        "created": 0,
        "lastUpdate": 0
      },
      "client": "string"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ConsentListResponse

Register a UserConsent

Code samples

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

POST /{tenant}/consents/{userId} HTTP/1.1

Content-Type: application/json
Accept: application/json

const inputBody = '{
  "name": "string",
  "version": "string",
  "document": {
    "language": "string",
    "version": "string"
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

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

POST /{tenant}/consents/{userId}

Registers a new UserConsent for the user identified by the userId in the path.

Body parameter

{
  "name": "string",
  "version": "string",
  "document": {
    "language": "string",
    "version": "string"
  }
}

Parameters

Name	In	Type	Required	Description
tenant	path	string	true	none
userId	path	string	true	none
body	body	RegisterConsentRequest	true	none

Example responses

201 Response

{
  "name": "string",
  "version": "string",
  "document": {
    "version": "string",
    "language": "string"
  },
  "status": "string",
  "gracePeriodEnds": "string"
}

Responses

Status	Meaning	Description	Schema
201	Created	none	ConsentResponse

Withdraw a UserConsent

Code samples

# You can also use wget
curl -X DELETE /{tenant}/consents/{userId}?id=string&delete=string \
  -H 'Authorization: Bearer {access-token}'

DELETE /{tenant}/consents/{userId}?id=string&delete=string HTTP/1.1


const headers = {
  'Authorization':'Bearer {access-token}'
};

fetch('/{tenant}/consents/{userId}?id=string&delete=string',
{
  method: 'DELETE',

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

DELETE /{tenant}/consents/{userId}

Removes a UserConsent from the user identified by the userId in the path. An audit trail is kept.

Parameters

Name	In	Type	Required	Description
tenant	path	string	true	none
userId	path	string	true	none
id	query	string	true	The identifier for the UserConsent. The `id` can be found in the response of the List all UserConsents endpoint.
delete	query	string	true	none

Responses

Status	Meaning	Description	Schema
200	OK	none	None

Confirm UserConsent

Code samples

# You can also use wget
curl -X POST /{tenant}/consents/confirm \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST /{tenant}/consents/confirm HTTP/1.1

Content-Type: application/json

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

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

POST /{tenant}/consents/confirm

Confirms the registration of a UserConsent in the second step of the double opt-in method. The request token that was sent by the EventHandler must be send along with the request.

Body parameter

{
  "requestToken": "string"
}

Parameters

Name	In	Type	Required	Description
tenant	path	string	true	none
body	body	ProcessRequestTokenRequest	true	none

Responses

Status	Meaning	Description	Schema
204	No Content	none	None

Reject UserConsent

Code samples

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

POST /{tenant}/consents/reject HTTP/1.1

Content-Type: application/json

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

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

POST /{tenant}/consents/reject

Rejects the registration of a UserConsent in the second step of the double opt-in method. The request token that was sent by the EventHandler must be send along with the request.

Body parameter

{
  "requestToken": "string"
}

Parameters

Name	In	Type	Required	Description
tenant	path	string	true	none
body	body	ProcessRequestTokenRequest	true	none

Responses

Status	Meaning	Description	Schema
204	No Content	none	None

ConsentDocumentResponse

{
  "version": "string",
  "language": "string"
}

Name	Type	Required	Restrictions	Description
version	string	true	none	The `documentVersion` of the ConsentDocument.
language	string	true	none	The `language` of the ConsentDocument.

ConsentResponse

{
  "name": "string",
  "version": "string",
  "document": {
    "version": "string",
    "language": "string"
  },
  "status": "string",
  "gracePeriodEnds": "string"
}

Name	Type	Required	Restrictions	Description
name	string	true	none	The `name` of the ConsentDefinition to which the document belongs.
version	string	true	none	The `version` of the ConsentVersion to which the document belongs.
document	ConsentDocumentResponse	true	none	none
status	string	true	none	none
gracePeriodEnds	string	false	none	none

MetaData

{
  "created": 0,
  "lastUpdate": 0
}

Name	Type	Required	Restrictions	Description
created	number	true	none	The timestamp indicating when this consent was first registered.
lastUpdate	number	true	none	The timestamp indicating when this consent was last updated.

ConsentListElementResponse

{
  "id": "string",
  "userId": "string",
  "consent": {
    "name": "string",
    "version": "string",
    "document": {
      "version": "string",
      "language": "string"
    },
    "status": "string",
    "gracePeriodEnds": "string"
  },
  "metaData": {
    "created": 0,
    "lastUpdate": 0
  },
  "client": "string"
}

Name	Type	Required	Restrictions	Description
id	string	true	none	An identifier for the UserConsent.
userId	string	true	none	none
consent	ConsentResponse	true	none	none
metaData	MetaData	true	none	none
client	string	true	none	none

ConsentListResponse

{
  "consents": [
    {
      "id": "string",
      "userId": "string",
      "consent": {
        "name": "string",
        "version": "string",
        "document": {
          "version": "string",
          "language": "string"
        },
        "status": "string",
        "gracePeriodEnds": "string"
      },
      "metaData": {
        "created": 0,
        "lastUpdate": 0
      },
      "client": "string"
    }
  ]
}

Name	Type	Required	Restrictions	Description
consents	[ConsentListElementResponse]	true	none	none

RegisterConsentDocumentRequest

{
  "language": "string",
  "version": "string"
}

Name	Type	Required	Restrictions	Description
language	string	true	none	The language (and/or other characteristics, such as country of residence) used to determine the audience for which this ConsentDocument applies. Each ConsentDocument only has one language.
version	string	true	none	An identifier for the document. The ConsentDocument is uniquely identified within the context of the ConsentVersion by the combination of `documentVersion` and `language`.

RegisterConsentRequest

{
  "name": "string",
  "version": "string",
  "document": {
    "language": "string",
    "version": "string"
  }
}

Name	Type	Required	Restrictions	Description
name	string	true	none	The identifier for the ConsentDefinition.
version	string	true	none	The identifier for the ConsentVersion.
document	RegisterConsentDocumentRequest	true	none	none

ProcessRequestTokenRequest

{
  "requestToken": "string"
}

Name	Type	Required	Restrictions	Description
requestToken	string	true	none	The token that was generated in the first step of registering a UserConsent with the double opt-in method (Register my UserConsent or Register a UserConsent). This token is sent by the EventHandler as configured by the tenant.

Relationship-based Access Control

The Scaled Access Relationship-based Access Control feature allows 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 Scaled Access

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 allows for a fast and scalable system to manage relationships (and thus the access to protected resources). Scaled Access 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 allows Scaled Access 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, the rule engine takes the restrictions for the requested RelationshipType into account.

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 Scaled Access. 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 Scaled Access, 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 Rules

Policy rules 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 policy rules can be specified by the tenant admin (see Configuration of Policies).

New tenants are set up according to a blueprint specifying default rules for use of the Relationship Management API. These rules 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 /tenants/{tenant}/groups/token-mapping \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /tenants/{tenant}/groups/token-mapping HTTP/1.1

Accept: application/json


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

fetch('/tenants/{tenant}/groups/token-mapping',
{
  method: 'GET',

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

GET /tenants/{tenant}/groups/token-mapping

Returns the TokenMapping configuration.

Parameters

Name	In	Type	Required	Description
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {
    "actorIdClaimPath": "string",
    "actorTypeClaimPath": "string"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	TokenMappingResponse

Update TokenMapping

Code samples

# You can also use wget
curl -X PUT /tenants/{tenant}/groups/token-mapping \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

PUT /tenants/{tenant}/groups/token-mapping HTTP/1.1

Content-Type: application/json
Accept: application/json

const inputBody = '{
  "actorIdClaimPath": "string",
  "actorTypeClaimPath": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/tenants/{tenant}/groups/token-mapping',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /tenants/{tenant}/groups/token-mapping

Updates the TokenMapping configuration.

Body parameter

{
  "actorIdClaimPath": "string",
  "actorTypeClaimPath": "string"
}

Parameters

Name	In	Type	Required	Description
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 /tenants/{tenant}/groups/authConfig \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /tenants/{tenant}/groups/authConfig HTTP/1.1

Accept: application/json


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

fetch('/tenants/{tenant}/groups/authConfig',
{
  method: 'GET',

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

GET /tenants/{tenant}/groups/authConfig

Returns the authorization configuration (JWKS and JWT details).

Parameters

Name	In	Type	Required	Description
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {
    "jwksUri": "string",
    "issuer": "string",
    "audience": "string"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	AuthorizationConfigResponse

Update authorization config

Code samples

# You can also use wget
curl -X PUT /tenants/{tenant}/groups/authConfig \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

PUT /tenants/{tenant}/groups/authConfig HTTP/1.1

Content-Type: application/json
Accept: application/json

const inputBody = '{
  "jwksUri": "string",
  "issuer": "string",
  "audience": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/tenants/{tenant}/groups/authConfig',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /tenants/{tenant}/groups/authConfig

Updates the authorization configuration (JWKS and JWT details)

Body parameter

{
  "jwksUri": "string",
  "issuer": "string",
  "audience": "string"
}

Parameters

Name	In	Type	Required	Description
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"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	AuthorizationConfigResponse

> RelationshipType Endpoints

List all RelationshipTypes

Code samples

# You can also use wget
curl -X GET /tenants/{tenant}/groups/relationship-types \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /tenants/{tenant}/groups/relationship-types HTTP/1.1

Accept: application/json


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

fetch('/tenants/{tenant}/groups/relationship-types',
{
  method: 'GET',

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

GET /tenants/{tenant}/groups/relationship-types

Lists all defined RelationshipTypes.

Parameters

Name	In	Type	Required	Description
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {}
}

Responses

Status	Meaning	Description	Schema
200	OK	none	RelationshipTypeListResponse

Get a RelationshipType

Code samples

# You can also use wget
curl -X GET /tenants/{tenant}/groups/relationship-types/{relationshipType} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /tenants/{tenant}/groups/relationship-types/{relationshipType} HTTP/1.1

Accept: application/json


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

fetch('/tenants/{tenant}/groups/relationship-types/{relationshipType}',
{
  method: 'GET',

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

GET /tenants/{tenant}/groups/relationship-types/{relationshipType}

Returns a specific RelationshipType.

Parameters

Name	In	Type	Required	Description
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"
      }
    ]
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	RelationshipTypeResponse

Create/update a RelationshipType and add a default policy

Code samples

# You can also use wget
curl -X PUT /tenants/{tenant}/groups/relationship-types/{relationshipType} \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access-token}'

PUT /tenants/{tenant}/groups/relationship-types/{relationshipType} HTTP/1.1

Content-Type: application/json

const inputBody = '{
  "description": "string",
  "restrictions": [
    {
      "from": "string",
      "to": "string"
    }
  ],
  "properties": [
    {
      "name": "isActive",
      "type": "boolean"
    }
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/tenants/{tenant}/groups/relationship-types/{relationshipType}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /tenants/{tenant}/groups/relationship-types/{relationshipType}

Creates or updates a RelationshipType. If the source node is an 'actor', this will also create a default policy of type '{source}:{relationship}:{target}:read', if you haven't already created this policy.

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

Body parameter

{
  "description": "string",
  "restrictions": [
    {
      "from": "string",
      "to": "string"
    }
  ],
  "properties": [
    {
      "name": "isActive",
      "type": "boolean"
    }
  ]
}

Parameters

Name	In	Type	Required	Description
relationshipType	path	string	true	The type of Relationship.
tenant	path	string	true	Your tenant code.
body	body	object	true	none
» description	body	string	false	A human-readable description for the RelationshipType.
» restrictions	body	array	false	A list of allowed ActorType/ResourceType combinations with a defined direction (`from`/`to`). The chosen Types must already exist.
»» from	body	string	true	The ActorType or ResourceType from which the Relationship can start.
»» to	body	string	true	The ActorType or ResourceType at which the Relationship can end.
» properties	body	[object]	false	none
»» name	body	string	false	none
»» type	body	string	false	none

Enumerated Values

Parameter	Value
»» type	string
»» type	number
»» type	date
»» type	boolean

Responses

Status	Meaning	Description	Schema
200	OK	none	None

> ResourceType Endpoints

List all ResourceTypes

Code samples

# You can also use wget
curl -X GET /tenants/{tenant}/groups/resources \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /tenants/{tenant}/groups/resources HTTP/1.1

Accept: application/json


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

fetch('/tenants/{tenant}/groups/resources',
{
  method: 'GET',

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

GET /tenants/{tenant}/groups/resources

Lists all defined ResourceTypes.

Parameters

Name	In	Type	Required	Description
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {}
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ResourceTypeListResponse

Get a ResourceType

Code samples

# You can also use wget
curl -X GET /tenants/{tenant}/groups/resources/{resourceType} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /tenants/{tenant}/groups/resources/{resourceType} HTTP/1.1

Accept: application/json


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

fetch('/tenants/{tenant}/groups/resources/{resourceType}',
{
  method: 'GET',

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

GET /tenants/{tenant}/groups/resources/{resourceType}

Returns a specific ResourceType.

Parameters

Name	In	Type	Required	Description
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": [
      {
        "name": "string",
        "type": "string"
      }
    ]
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ResourceTypeResponse

Create/update a ResourceType

Code samples

# You can also use wget
curl -X PUT /tenants/{tenant}/groups/resources/{resourceType} \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access-token}'

PUT /tenants/{tenant}/groups/resources/{resourceType} HTTP/1.1

Content-Type: application/json

const inputBody = '{
  "description": "Pet",
  "properties": [
    {
      "name": "age",
      "type": "number"
    },
    {
      "name": "name",
      "type": "string"
    }
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/tenants/{tenant}/groups/resources/{resourceType}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /tenants/{tenant}/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 attributes.

Body parameter

{
  "description": "Pet",
  "properties": [
    {
      "name": "age",
      "type": "number"
    },
    {
      "name": "name",
      "type": "string"
    }
  ]
}

Parameters

Name	In	Type	Required	Description
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

> ActorType Endpoints

List all ActorTypes

Code samples

# You can also use wget
curl -X GET /tenants/{tenant}/groups/actors \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /tenants/{tenant}/groups/actors HTTP/1.1

Accept: application/json


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

fetch('/tenants/{tenant}/groups/actors',
{
  method: 'GET',

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

GET /tenants/{tenant}/groups/actors

Lists all defined ActorTypes.

Parameters

Name	In	Type	Required	Description
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {}
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ActorTypeListResponse

Get an ActorType

Code samples

# You can also use wget
curl -X GET /tenants/{tenant}/groups/actors/{actorType} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /tenants/{tenant}/groups/actors/{actorType} HTTP/1.1

Accept: application/json


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

fetch('/tenants/{tenant}/groups/actors/{actorType}',
{
  method: 'GET',

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

GET /tenants/{tenant}/groups/actors/{actorType}

Returns a specific ActorType.

Parameters

Name	In	Type	Required	Description
actorType	path	string	true	none
tenant	path	string	true	Your tenant code.
resourceType	path	string	true	The type of Resource.

Example responses

200 Response

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {
    "name": "string",
    "description": "string",
    "properties": [
      {
        "name": "string",
        "type": "string"
      }
    ]
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	ActorTypeResponse

Create/update an ActorType and add a default policy

Code samples

# You can also use wget
curl -X PUT /tenants/{tenant}/groups/actors/{actorType} \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access-token}'

PUT /tenants/{tenant}/groups/actors/{actorType} HTTP/1.1

Content-Type: application/json

const inputBody = '{
  "description": "User",
  "properties": [
    {
      "name": "string",
      "type": "string"
    }
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/tenants/{tenant}/groups/actors/{actorType}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /tenants/{tenant}/groups/actors/{actorType}

Creates or updates an ActorType. This will also create a default policy of type '{actorType}:read', if you haven't already created this policy.

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

Body parameter

{
  "description": "User",
  "properties": [
    {
      "name": "string",
      "type": "string"
    }
  ]
}

Parameters

Name	In	Type	Required	Description
actorType	path	string	true	none
tenant	path	string	true	Your tenant code.
resourceType	path	string	true	The type of Resource.
body	body	SaveActorTypeRequest	true	none

Responses

Status	Meaning	Description	Schema
200	OK	none	None

Schemas

RelationshipTypeListResponse

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {}
}

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.

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

{
  "name": "string",
  "type": "string"
}

Name	Type	Required	Restrictions	Description
name	string	true	none	The name of the property. Only alphanumeric characters and underscores are allowed.
type	string	true	none	The type of the property. One of 'string', 'number', 'boolean', 'date'.

Enumerated Values

Property	Value
type	string
type	number
type	boolean
type	date

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"
      }
    ]
  }
}

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.

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"
  }
}

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.

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": {}
}

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.

ResourceTypeConfig

{
  "name": "string",
  "description": "string",
  "properties": [
    {
      "name": "string",
      "type": "string"
    }
  ]
}

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	[ElementTypeProperty]	false	none	Custom properties of the ResourceType.

ResourceTypeResponse

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {
    "name": "string",
    "description": "string",
    "properties": [
      {
        "name": "string",
        "type": "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.

SaveResourceTypeRequest

{
  "description": "Pet",
  "properties": [
    {
      "name": "age",
      "type": "number"
    },
    {
      "name": "name",
      "type": "string"
    }
  ]
}

Name	Type	Required	Restrictions	Description
description	object	false	none	A human-readable description for the ResourceType.
properties	[ElementTypeProperty]	false	none	Custom properties of the ResourceType.

ActorTypeListResponse

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {}
}

Name	Type	Required	Restrictions	Description
resources	[string]	true	none	A list of the ActorTypes.
links	object	true	none	The URI's of the linked resources.
config	object	false	none	The object describing the requested config.

ActorTypeConfig

{
  "name": "string",
  "description": "string",
  "properties": [
    {
      "name": "string",
      "type": "string"
    }
  ]
}

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	[ElementTypeProperty]	false	none	Custom properties of the ActorType.

ActorTypeResponse

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {
    "name": "string",
    "description": "string",
    "properties": [
      {
        "name": "string",
        "type": "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	ActorTypeConfig	false	none	The object describing the requested config.

SaveActorTypeRequest

{
  "description": "User",
  "properties": [
    {
      "name": "string",
      "type": "string"
    }
  ]
}

Name	Type	Required	Restrictions	Description
description	object	false	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"
  }
}

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.

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.

Relationship Management API

Get JSON Web Key Set

Code samples

# You can also use wget
curl -X GET /{tenant}/.well-known/jwks.json

GET /{tenant}/.well-known/jwks.json HTTP/1.1


fetch('/{tenant}/.well-known/jwks.json',
{
  method: 'GET'

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

GET /{tenant}/.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
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 /{tenant}/actors/me \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /{tenant}/actors/me HTTP/1.1

Accept: application/json


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

fetch('/{tenant}/actors/me',
{
  method: 'GET',

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

GET /{tenant}/actors/me

Returns the Actor authenticated by the user access token.

Parameters

Name	In	Type	Required	Description
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.

{
  "action": "${principal.nodeType}:read",
  "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}:read) by using the Authorization Config API.

Create/update my Actor

Code samples

# You can also use wget
curl -X PUT /{tenant}/actors/me \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

PUT /{tenant}/actors/me HTTP/1.1

Content-Type: application/json
Accept: application/json

const inputBody = '{
  "customAttribute1": "value1",
  "customAttribute2": "value2"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

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

PUT /{tenant}/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 doesn't 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
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.

{
  "action": "${principal.nodeType}:<createOrUpdate>",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}"
  }
}

Authorization Request

List my Relationships

Code samples

# You can also use wget
curl -X GET /{tenant}/actors/me/relationships \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /{tenant}/actors/me/relationships HTTP/1.1

Accept: application/json


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

fetch('/{tenant}/actors/me/relationships',
{
  method: 'GET',

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

GET /{tenant}/actors/me/relationships

List all Relationships of the Actor authenticated by the user access token.

Parameters

Name	In	Type	Required	Description
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.
direction	query	string	false	Optional direction (`from` or `to`) of the Relationship with respect to the Actor authenticated by the user access token.
relationship-types	query	string	false	Optional comma-separated list of RelationshipTypes to filter on.
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"
    },
    "to": {
      "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	[RelationshipResponse]	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	NodeResponse	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.
» to	NodeResponse	true	none	none
» properties	object	false	none	The custom properties of the Relationship.

{
  "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

Create my Relationship

Code samples

# You can also use wget
curl -X POST /{tenant}/actors/me/relationships \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST /{tenant}/actors/me/relationships HTTP/1.1

Content-Type: application/json
Accept: application/json

const inputBody = '{
  "relationshipType": "string",
  "to": {
    "id": "string",
    "type": "string"
  },
  "properties": {
    "customAttribute1": "string",
    "customAttribute2": true
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/{tenant}/actors/me/relationships',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /{tenant}/actors/me/relationships

Creates a Relationship for the Actor authenticated by the user access token. 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
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.

Example responses

200 Response

{
  "id": "string",
  "relationshipType": "string",
  "from": {
    "id": "string",
    "type": "string"
  },
  "to": {
    "id": "string",
    "type": "string"
  },
  "properties": {}
}

Responses

Status	Meaning	Description	Schema
200	OK	none	RelationshipDetailResponse

{
  "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

Get my Relationship

Code samples

# You can also use wget
curl -X GET /{tenant}/actors/me/relationships/{relationshipId} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /{tenant}/actors/me/relationships/{relationshipId} HTTP/1.1

Accept: application/json


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

fetch('/{tenant}/actors/me/relationships/{relationshipId}',
{
  method: 'GET',

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

GET /{tenant}/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
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"
  },
  "to": {
    "id": "string",
    "type": "string"
  },
  "properties": {}
}

Responses

Status	Meaning	Description	Schema
200	OK	none	RelationshipDetailResponse

{
  "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

Update my Relationship

Code samples

# You can also use wget
curl -X PUT /{tenant}/actors/me/relationships/{relationshipId} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

PUT /{tenant}/actors/me/relationships/{relationshipId} HTTP/1.1

Content-Type: application/json
Accept: application/json

const inputBody = '{
  "relationshipType": "string",
  "to": {
    "id": "string",
    "type": "string"
  },
  "properties": {
    "customAttribute1": "string",
    "customAttribute2": true
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/{tenant}/actors/me/relationships/{relationshipId}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /{tenant}/actors/me/relationships/{relationshipId}

Updates the Relationship specified by {relationshipId} from the Actor authenticated by the user access token.

Body parameter

{
  "relationshipType": "string",
  "to": {
    "id": "string",
    "type": "string"
  },
  "properties": {
    "customAttribute1": "string",
    "customAttribute2": true
  }
}

Parameters

Name	In	Type	Required	Description
relationshipId	path	string	true	The identifier for the Relationship.
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.

Example responses

200 Response

{
  "id": "string",
  "relationshipType": "string",
  "from": {
    "id": "string",
    "type": "string"
  },
  "to": {
    "id": "string",
    "type": "string"
  },
  "properties": {}
}

Responses

Status	Meaning	Description	Schema
200	OK	none	RelationshipDetailResponse

{
  "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

Delete my Relationship

Code samples

# You can also use wget
curl -X DELETE /{tenant}/actors/me/relationships/{relationshipId} \
  -H 'Authorization: Bearer {access-token}'

DELETE /{tenant}/actors/me/relationships/{relationshipId} HTTP/1.1


const headers = {
  'Authorization':'Bearer {access-token}'
};

fetch('/{tenant}/actors/me/relationships/{relationshipId}',
{
  method: 'DELETE',

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

DELETE /{tenant}/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
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

{
  "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

> Actor Endpoints

List all Actors of type

Code samples

# You can also use wget
curl -X GET /{tenant}/actors/{actorType} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /{tenant}/actors/{actorType} HTTP/1.1

Accept: application/json


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

fetch('/{tenant}/actors/{actorType}',
{
  method: 'GET',

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

GET /{tenant}/actors/{actorType}

Returns all Actors of the specified {actorType}.

Parameters

Name	In	Type	Required	Description
actorType	path	string	true	The type of Actor.
tenant	path	string	true	Your tenant code.

Example responses

200 Response

[
  {
    "id": "string",
    "type": "string"
  }
]

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.

{
  "action": "${params.actorType}:list",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "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}:list) by using the Authorization Config API.

Create an Actor

Code samples

# You can also use wget
curl -X POST /{tenant}/actors/{actorType} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST /{tenant}/actors/{actorType} HTTP/1.1

Content-Type: application/json
Accept: application/json

const inputBody = '{
  "customAttribute1": "value1",
  "customAttribute2": "value2"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/{tenant}/actors/{actorType}',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /{tenant}/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
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.

{
  "action": "${params.actorType}:create",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "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}:create) by using the Authorization Config API.

Get an Actor

Code samples

# You can also use wget
curl -X GET /{tenant}/actors/{actorType}/{actorId} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /{tenant}/actors/{actorType}/{actorId} HTTP/1.1

Accept: application/json


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

fetch('/{tenant}/actors/{actorType}/{actorId}',
{
  method: 'GET',

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

GET /{tenant}/actors/{actorType}/{actorId}

Returns the Actor specified by {actorType} and {actorId}.

Parameters

Name	In	Type	Required	Description
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.

{
  "action": "${params.actorType}:read",
  "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}:read) by using the Authorization Config API.

Create/update an Actor

Code samples

# You can also use wget
curl -X PUT /{tenant}/actors/{actorType}/{actorId} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

PUT /{tenant}/actors/{actorType}/{actorId} HTTP/1.1

Content-Type: application/json
Accept: application/json

const inputBody = '{
  "customAttribute1": "value1",
  "customAttribute2": "value2"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/{tenant}/actors/{actorType}/{actorId}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /{tenant}/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 doesn't 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
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.

{
  "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 /{tenant}/actors/{actorType}/{actorId} \
  -H 'Authorization: Bearer {access-token}'

DELETE /{tenant}/actors/{actorType}/{actorId} HTTP/1.1


const headers = {
  'Authorization':'Bearer {access-token}'
};

fetch('/{tenant}/actors/{actorType}/{actorId}',
{
  method: 'DELETE',

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

DELETE /{tenant}/actors/{actorType}/{actorId}

Removes the Actor specified by {actorType} and {actorId}.

Parameters

Name	In	Type	Required	Description
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

{
  "action": "${params.actorType}:delete",
  "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}:delete) by using the Authorization Config API.

List all Relationships

Code samples

# You can also use wget
curl -X GET /{tenant}/actors/{actorType}/{actorId}/relationships \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /{tenant}/actors/{actorType}/{actorId}/relationships HTTP/1.1

Accept: application/json


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

fetch('/{tenant}/actors/{actorType}/{actorId}/relationships',
{
  method: 'GET',

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

GET /{tenant}/actors/{actorType}/{actorId}/relationships

Returns all Relationships of the Actor specified by {actorType} and {actorId}.

Parameters

Name	In	Type	Required	Description
actorType	path	string	true	The type of Actor.
actorId	path	string	true	The identifier for the Actor.
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.
direction	query	string	false	Optional direction (`from` or `to`) of the Relationship with respect to the Actor specified by {actorType} and {actorId}.
relationship-types	query	string	false	Optional comma-separated list of RelationshipTypes to filter on.
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"
    },
    "to": {
      "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	[RelationshipResponse]	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	NodeResponse	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.
» to	NodeResponse	true	none	none
» properties	object	false	none	The custom properties of the Relationship.

{
  "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 /{tenant}/actors/{actorType}/{actorId}/relationships \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST /{tenant}/actors/{actorType}/{actorId}/relationships HTTP/1.1

Content-Type: application/json
Accept: application/json

const inputBody = '{
  "relationshipType": "string",
  "to": {
    "id": "string",
    "type": "string"
  },
  "properties": {
    "customAttribute1": "string",
    "customAttribute2": true
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/{tenant}/actors/{actorType}/{actorId}/relationships',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /{tenant}/actors/{actorType}/{actorId}/relationships

Creates a Relationship for the Actor specified by {actorType} and {actorId}. 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
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.

Example responses

200 Response

{
  "id": "string",
  "relationshipType": "string",
  "from": {
    "id": "string",
    "type": "string"
  },
  "to": {
    "id": "string",
    "type": "string"
  },
  "properties": {}
}

Responses

Status	Meaning	Description	Schema
200	OK	none	RelationshipDetailResponse

{
  "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 /{tenant}/actors/{actorType}/{actorId}/relationships/{relationshipId} \
  -H 'Authorization: Bearer {access-token}'

DELETE /{tenant}/actors/{actorType}/{actorId}/relationships/{relationshipId} HTTP/1.1


const headers = {
  'Authorization':'Bearer {access-token}'
};

fetch('/{tenant}/actors/{actorType}/{actorId}/relationships/{relationshipId}',
{
  method: 'DELETE',

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

DELETE /{tenant}/actors/{actorType}/{actorId}/relationships/{relationshipId}

Removes the Relationship specified by {relationshipId}.

Parameters

Name	In	Type	Required	Description
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

{
  "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 /{tenant}/actors/{actorType}/{actorId}/relationships/{relationshipId} \
  -H 'Authorization: Bearer {access-token}'

GET /{tenant}/actors/{actorType}/{actorId}/relationships/{relationshipId} HTTP/1.1


const headers = {
  'Authorization':'Bearer {access-token}'
};

fetch('/{tenant}/actors/{actorType}/{actorId}/relationships/{relationshipId}',
{
  method: 'GET',

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

GET /{tenant}/actors/{actorType}/{actorId}/relationships/{relationshipId}

Gets the Relationship specified by {relationshipId}

Parameters

Name	In	Type	Required	Description
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

{
  "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 /{tenant}/actors/{actorType}/{actorId}/relationships/{relationshipId} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

PUT /{tenant}/actors/{actorType}/{actorId}/relationships/{relationshipId} HTTP/1.1

Content-Type: application/json
Accept: application/json

const inputBody = '{
  "relationshipType": "string",
  "to": {
    "id": "string",
    "type": "string"
  },
  "properties": {
    "customAttribute1": "string",
    "customAttribute2": true
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/{tenant}/actors/{actorType}/{actorId}/relationships/{relationshipId}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /{tenant}/actors/{actorType}/{actorId}/relationships/{relationshipId}

Update a Relationship of the Actor specified by {actorType}, {actorId} and {relationshipId}

Body parameter

{
  "relationshipType": "string",
  "to": {
    "id": "string",
    "type": "string"
  },
  "properties": {
    "customAttribute1": "string",
    "customAttribute2": true
  }
}

Parameters

Name	In	Type	Required	Description
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
» relationshipType	body	string	true	The type of relationship.
» to	body	object	true	The target Actor/Resource in the Relationship.

Example responses

200 Response

{
  "id": "string",
  "relationshipType": "string",
  "from": {
    "id": "string",
    "type": "string"
  },
  "to": {
    "id": "string",
    "type": "string"
  },
  "properties": {}
}

Responses

Status	Meaning	Description	Schema
200	OK	none	RelationshipDetailResponse

{
  "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 /{tenant}/sharing/invitations/me \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /{tenant}/sharing/invitations/me HTTP/1.1

Accept: application/json


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

fetch('/{tenant}/sharing/invitations/me',
{
  method: 'GET',

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

GET /{tenant}/sharing/invitations/me

Lists all Invitations linked to the Actor authenticated by the user access token.

Parameters

Name	In	Type	Required	Description
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",
    "relationshipType": "string",
    "relationshipDirectionForSubject": "from",
    "inviteeContactType": "email",
    "inviteeContactValue": "invitee@example.com",
    "isCreatedBy": {
      "id": "string",
      "type": "user"
    },
    "targets": {
      "id": "string",
      "type": "string"
    },
    "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.
» relationshipType	string	true	none	The type of relationship suggested for the target and the invitee.
» relationshipDirectionForSubject	string	true	none	The role of the target in the Relationship. The Relationship can start from (`from`) or end at (`to`) the target.
» 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.
» targets	object	true	none	The Actor/Resource for which a Relationship is suggested in the invitation.
» isAcceptedBy	object	false	none	The Actor that accepted the invitation.
» isRevokedBy	object	false	none	The Actor that withdrew the invitation.

{
  "action": "invitations:list",
  "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 invitations:list) by using the Authorization Config API.

List all Invitations

Code samples

# You can also use wget
curl -X GET /{tenant}/sharing/invitations?id=string&type=string \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /{tenant}/sharing/invitations?id=string&type=string HTTP/1.1

Accept: application/json


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

fetch('/{tenant}/sharing/invitations?id=string&type=string',
{
  method: 'GET',

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

GET /{tenant}/sharing/invitations

Lists all Invitations linked to a specified Actor or Resource.

Parameters

Name	In	Type	Required	Description
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",
    "relationshipType": "string",
    "relationshipDirectionForSubject": "from",
    "inviteeContactType": "email",
    "inviteeContactValue": "invitee@example.com",
    "isCreatedBy": {
      "id": "string",
      "type": "user"
    },
    "targets": {
      "id": "string",
      "type": "string"
    },
    "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.
» relationshipType	string	true	none	The type of relationship suggested for the target and the invitee.
» relationshipDirectionForSubject	string	true	none	The role of the target in the Relationship. The Relationship can start from (`from`) or end at (`to`) the target.
» 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.
» targets	object	true	none	The Actor/Resource for which a Relationship is suggested in the invitation.
» isAcceptedBy	object	false	none	The Actor that accepted the invitation.
» isRevokedBy	object	false	none	The Actor that withdrew the invitation.

{
  "action": "invitations:list",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${query[\"id\"]}",
    "type": "${query[\"type\"]}"
  }
}

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 invitations:list) by using the Authorization Config API.

Create an Invitation

Code samples

# You can also use wget
curl -X POST /{tenant}/sharing/invitations \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST /{tenant}/sharing/invitations HTTP/1.1

Content-Type: application/json
Accept: application/json

const inputBody = '{
  "relationshipType": "string",
  "to": {
    "id": "string",
    "type": "string"
  },
  "invitor": {
    "id": "string",
    "type": "string"
  },
  "invitee": {
    "contact": {
      "type": "email",
      "value": "string"
    }
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/{tenant}/sharing/invitations',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /{tenant}/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

{
  "relationshipType": "string",
  "to": {
    "id": "string",
    "type": "string"
  },
  "invitor": {
    "id": "string",
    "type": "string"
  },
  "invitee": {
    "contact": {
      "type": "email",
      "value": "string"
    }
  }
}

Parameters

Name	In	Type	Required	Description
body	body	object	true	none
» relationshipType	body	string	true	The type of relationship suggested for the target and the invitee.
» 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.
» 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.

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

{
  "action": "${!!body.from ? body.from.type : 'user'}:${body.relationshipType}:${!!body.from ? 'user' : body.to.type}:invitation:create",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${!!body.from ? body.from.id : ''}",
      "type": "${!!body.from ? body.from.type : 'user'}"
    },
    "to": {
      "id": "${!!body.to ? body.to.id : ''}",
      "type": "${!!body.to ? body.to.type : 'user'}"
    },
    "direction": "${!!body.from ? \"from\" : \"to\"}",
    "invitor": {
      "id": "${body.invitor && body.invitor.id || principal.nodeId}",
      "type": "${body.invitor && body.invitor.type || principal.nodeType}"
    },
    "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 ${!!body.from ? body.from.type : 'user'}:${body.relationshipType}:${!!body.from ? 'user' : body.to.type}:invitation:create) by using the Authorization Config API.

Get an invitation

Code samples

# You can also use wget
curl -X GET /{tenant}/sharing/invitations/{invitationId} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /{tenant}/sharing/invitations/{invitationId} HTTP/1.1

Accept: application/json


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

fetch('/{tenant}/sharing/invitations/{invitationId}',
{
  method: 'GET',

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

GET /{tenant}/sharing/invitations/{invitationId}

Returns the Invitation specified by {invitationId}.

Parameters

Name	In	Type	Required	Description
invitationId	path	string	true	The identifier for the Invitation.
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "id": "string",
  "type": "invitation",
  "relationshipType": "string",
  "relationshipDirectionForSubject": "from",
  "inviteeContactType": "email",
  "inviteeContactValue": "invitee@example.com",
  "isCreatedBy": {
    "id": "string",
    "type": "user"
  },
  "targets": {
    "id": "string",
    "type": "string"
  },
  "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.
» relationshipType	string	true	none	The type of relationship suggested for the target and the invitee.
» relationshipDirectionForSubject	string	true	none	The role of the target in the Relationship. The Relationship can start from (`from`) or end at (`to`) the target.
» 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.
» targets	object	true	none	The Actor/Resource for which a Relationship is suggested in the invitation.
» isAcceptedBy	object	false	none	The Actor that accepted the invitation.
» isRevokedBy	object	false	none	The Actor that withdrew the invitation.

{
  "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 /{tenant}/sharing/invitations/{invitationId} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

PUT /{tenant}/sharing/invitations/{invitationId} HTTP/1.1

Accept: application/json


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

fetch('/{tenant}/sharing/invitations/{invitationId}',
{
  method: 'PUT',

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

PUT /{tenant}/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.

Parameters

Name	In	Type	Required	Description
invitationId	path	string	true	The identifier for the Invitation.
tenant	path	string	true	Your tenant code.

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

{
  "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 /{tenant}/sharing/invitations/accept \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST /{tenant}/sharing/invitations/accept HTTP/1.1

Content-Type: application/json

const inputBody = '{
  "acceptor": {
    "id": "string",
    "type": "string"
  },
  "requestToken": "string",
  "properties": {
    "isActive": "true"
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/{tenant}/sharing/invitations/accept',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /{tenant}/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
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.

Responses

Status	Meaning	Description	Schema
200	OK	none	None

{
  "action": "invitations: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}"
  }
}

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 invitations:accept) by using the Authorization Config API.

Withdraw an Invitation

Code samples

# You can also use wget
curl -X POST /{tenant}/sharing/invitations/withdraw \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST /{tenant}/sharing/invitations/withdraw HTTP/1.1

Content-Type: application/json

const inputBody = '{
  "revocator": {
    "id": "string",
    "type": "string"
  },
  "invitationId": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/{tenant}/sharing/invitations/withdraw',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /{tenant}/sharing/invitations/withdraw

Withdraws an Invitation.

Body parameter

{
  "revocator": {
    "id": "string",
    "type": "string"
  },
  "invitationId": "string"
}

Parameters

Name	In	Type	Required	Description
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

{
  "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.

> Resource Endpoints

List all Resources of type

Code samples

# You can also use wget
curl -X GET /{tenant}/resources/{resourceType} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /{tenant}/resources/{resourceType} HTTP/1.1

Accept: application/json


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

fetch('/{tenant}/resources/{resourceType}',
{
  method: 'GET',

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

GET /{tenant}/resources/{resourceType}

Returns all Resources of the specified {resourceType}.

Parameters

Name	In	Type	Required	Description
resourceType	path	string	true	The type of Resource.
tenant	path	string	true	Your tenant code.

Example responses

200 Response

[
  {
    "id": "string",
    "type": "string"
  }
]

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.

{
  "action": "${params.resourceType}:list",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "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}:list) by using the Authorization Config API.

Create a Resource

Code samples

# You can also use wget
curl -X POST /{tenant}/resources/{resourceType} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST /{tenant}/resources/{resourceType} HTTP/1.1

Content-Type: application/json
Accept: application/json

const inputBody = '{
  "customAttribute1": "value1",
  "customAttribute2": "value2"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/{tenant}/resources/{resourceType}',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /{tenant}/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
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.

{
  "action": "${params.resourceType}:create",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "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}:create) by using the Authorization Config API.

Get a Resource

Code samples

# You can also use wget
curl -X GET /{tenant}/resources/{resourceType}/{resourceId} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /{tenant}/resources/{resourceType}/{resourceId} HTTP/1.1

Accept: application/json


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

fetch('/{tenant}/resources/{resourceType}/{resourceId}',
{
  method: 'GET',

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

GET /{tenant}/resources/{resourceType}/{resourceId}

Returns the Resource specified by {resourceType} and {resourceId}.

Parameters

Name	In	Type	Required	Description
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.

{
  "action": "${params.resourceType}:read",
  "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}:read) by using the Authorization Config API.

Create/update a Resource

Code samples

# You can also use wget
curl -X PUT /{tenant}/resources/{resourceType}/{resourceId} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

PUT /{tenant}/resources/{resourceType}/{resourceId} HTTP/1.1

Content-Type: application/json
Accept: application/json

const inputBody = '{
  "customAttribute1": "value1",
  "customAttribute2": "value2"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/{tenant}/resources/{resourceType}/{resourceId}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /{tenant}/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 doesn't 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
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.

{
  "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 /{tenant}/resources/{resourceType}/{resourceId} \
  -H 'Authorization: Bearer {access-token}'

DELETE /{tenant}/resources/{resourceType}/{resourceId} HTTP/1.1


const headers = {
  'Authorization':'Bearer {access-token}'
};

fetch('/{tenant}/resources/{resourceType}/{resourceId}',
{
  method: 'DELETE',

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

DELETE /{tenant}/resources/{resourceType}/{resourceId}

Removes the Resource specified by {resourceType} and {resourceId}.

Parameters

Name	In	Type	Required	Description
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

{
  "action": "${params.resourceType}:delete",
  "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}:delete) by using the Authorization Config API.

List all Relationships

Code samples

# You can also use wget
curl -X GET /{tenant}/resources/{resourceType}/{resourceId}/relationships \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /{tenant}/resources/{resourceType}/{resourceId}/relationships HTTP/1.1

Accept: application/json


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

fetch('/{tenant}/resources/{resourceType}/{resourceId}/relationships',
{
  method: 'GET',

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

GET /{tenant}/resources/{resourceType}/{resourceId}/relationships

Returns all Relationships of the Resource specified by {resourceType} and {resourceId}.

Parameters

Name	In	Type	Required	Description
resourceType	path	string	true	The type of Resource.
resourceId	path	string	true	The identifier for the Resource.
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.
direction	query	string	false	Optional direction (`from` or `to`) of the Relationship with respect to the Resource specified by {resourceType} and {resourceId}.
relationship-types	query	string	false	Optional comma-separated list of RelationshipTypes to filter on.
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"
    },
    "to": {
      "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	[RelationshipResponse]	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	NodeResponse	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.
» to	NodeResponse	true	none	none
» properties	object	false	none	The custom properties of the Relationship.

{
  "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 /{tenant}/resources/{resourceType}/{resourceId}/relationships \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST /{tenant}/resources/{resourceType}/{resourceId}/relationships HTTP/1.1

Content-Type: application/json
Accept: application/json

const inputBody = '{
  "relationshipType": "string",
  "to": {
    "id": "string",
    "type": "string"
  },
  "properties": {
    "customAttribute1": "string",
    "customAttribute2": true
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/{tenant}/resources/{resourceType}/{resourceId}/relationships',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /{tenant}/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
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.

Example responses

200 Response

{
  "id": "string",
  "relationshipType": "string",
  "from": {
    "id": "string",
    "type": "string"
  },
  "to": {
    "id": "string",
    "type": "string"
  },
  "properties": {}
}

Responses

Status	Meaning	Description	Schema
200	OK	none	RelationshipDetailResponse

{
  "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 /{tenant}/resources/{resourceType}/{resourceId}/relationships/{relationshipId} \
  -H 'Authorization: Bearer {access-token}'

DELETE /{tenant}/resources/{resourceType}/{resourceId}/relationships/{relationshipId} HTTP/1.1


const headers = {
  'Authorization':'Bearer {access-token}'
};

fetch('/{tenant}/resources/{resourceType}/{resourceId}/relationships/{relationshipId}',
{
  method: 'DELETE',

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

DELETE /{tenant}/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
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.

Responses

Status	Meaning	Description	Schema
200	OK	none	None

{
  "action": "${params.resourceType}:<relationshipType>:<targetType>:delete",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${params.resourceId}",
      "type": "${params.resourceType}"
    },
    "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.resourceType}:<relationshipType>:<targetType>:delete) by using the Authorization Config API.

Get a Relationship

Code samples

# You can also use wget
curl -X GET /{tenant}/resources/{resourceType}/{resourceId}/relationships/{relationshipId} \
  -H 'Authorization: Bearer {access-token}'

GET /{tenant}/resources/{resourceType}/{resourceId}/relationships/{relationshipId} HTTP/1.1


const headers = {
  'Authorization':'Bearer {access-token}'
};

fetch('/{tenant}/resources/{resourceType}/{resourceId}/relationships/{relationshipId}',
{
  method: 'GET',

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

GET /{tenant}/resources/{resourceType}/{resourceId}/relationships/{relationshipId}

Returns the Relationship specified by {relationshipId}, of the Resource specified by {resourceType} and {resourceId}.

Parameters

Name	In	Type	Required	Description
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.

Responses

Status	Meaning	Description	Schema
200	OK	none	None

{
  "action": "${params.resourceType}:<relationshipType>:<targetType>:read",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${params.resourceId}",
      "type": "${params.resourceType}"
    },
    "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.resourceType}:<relationshipType>:<targetType>:read) by using the Authorization Config API.

Update a Relationship

Code samples

# You can also use wget
curl -X PUT /{tenant}/resources/{resourceType}/{resourceId}/relationships/{relationshipId} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

PUT /{tenant}/resources/{resourceType}/{resourceId}/relationships/{relationshipId} HTTP/1.1

Content-Type: application/json
Accept: application/json

const inputBody = '{
  "relationshipType": "string",
  "to": {
    "id": "string",
    "type": "string"
  },
  "properties": {
    "customAttribute1": "string",
    "customAttribute2": true
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/{tenant}/resources/{resourceType}/{resourceId}/relationships/{relationshipId}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /{tenant}/resources/{resourceType}/{resourceId}/relationships/{relationshipId}

Update the Relationship specified by {relationshipId}, of the Resource specified by {resourceType} and {resourceId}.

Body parameter

{
  "relationshipType": "string",
  "to": {
    "id": "string",
    "type": "string"
  },
  "properties": {
    "customAttribute1": "string",
    "customAttribute2": true
  }
}

Parameters

Name	In	Type	Required	Description
resourceType	path	string	true	The type of Resource.
resourceId	path	string	true	The identifier for the Resource.
relationshipId	path	string	true	The identifier for the Relationship.
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.

Example responses

200 Response

{
  "id": "string",
  "relationshipType": "string",
  "from": {
    "id": "string",
    "type": "string"
  },
  "to": {
    "id": "string",
    "type": "string"
  },
  "properties": {}
}

Responses

Status	Meaning	Description	Schema
200	OK	none	RelationshipDetailResponse

{
  "action": "${params.resourceType}:<relationshipType>:<targetType>:update",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${params.resourceId}",
      "type": "${params.resourceType}"
    },
    "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.resourceType}:<relationshipType>:<targetType>:update) by using the Authorization Config API.

Schemas

NodeResponse

{
  "id": "string",
  "type": "string"
}

Name	Type	Required	Restrictions	Description
id	string	true	none	The identifier of the Actor/Resource.
type	string	true	none	The `actorType` or `resourceType` of the Actor/Resource.

RelationshipResponse

{
  "id": "string",
  "relationshipType": "string",
  "from": {
    "id": "string",
    "type": "string"
  },
  "to": {
    "id": "string",
    "type": "string"
  },
  "properties": {}
}

Name	Type	Required	Restrictions	Description
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	NodeResponse	true	none	none
to	NodeResponse	true	none	none
properties	object	false	none	The custom properties of the Relationship.

NodeDetailResponse

{
  "id": "string",
  "type": "string"
}

Name	Type	Required	Restrictions	Description
id	string	true	none	The identifier of the Actor/Resource.
type	string	true	none	The `actorType` or `resourceType` of the Actor/Resource.

RelationshipDetailResponse

{
  "id": "string",
  "relationshipType": "string",
  "from": {
    "id": "string",
    "type": "string"
  },
  "to": {
    "id": "string",
    "type": "string"
  },
  "properties": {}
}

Name	Type	Required	Restrictions	Description
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
to	NodeDetailResponse	true	none	none
properties	object	false	none	The custom properties of the Relationship.

ActorResponse

{
  "id": "string",
  "type": "string"
}

Name	Type	Required	Restrictions	Description
id	string	true	none	The identifier of the Actor.
type	string	true	none	The type of Actor.

CreateInvitationResponse

{
  "invitationId": "string",
  "requestToken": "string"
}

Name	Type	Required	Restrictions	Description
invitationId	string	true	read-only	none
requestToken	string	true	read-only	none

ResourceResponse

{
  "id": "string",
  "type": "string"
}

Name	Type	Required	Restrictions	Description
id	string	true	none	The identifier of the Resource.
type	string	true	none	The type of Resource.

Email Management

The Mail API allows Scaled Access customers to send email according to a specified template.

Overview and Concepts

Setup

To set the sender of the email to an email address of your domain (e.g. noreply@mybrand.com), your domain must be verified at the Scaled Access AWS.

Request to verify your domain via support@scaledaccess.com.
Add a TXT record to your domain's DNS server with the Name and Value provided by Scaled Access.
- If your DNS provider does not allow underscores in record names, you can omit "_amazonses" from the Name.
- To help you easily identify this record within your domain's DNS settings, you can optionally prefix the Value with "amazonses: ".
- Some DNS providers automatically append the domain name to DNS record names. To avoid duplication of the domain name, you can add a period to the end of the domain name in the DNS record. This indicates that the record name is fully qualified and the DNS provider need not append an additional domain name.

Templates

The relationship-invitation template

Emails constructed with this template will be formed as follows:

Hello {name},

You've been invited to join {application}. To accept this invitation, click on this link, or navigate to this URL in your browser: {actionUrl}

Thank you

Configuration of the Mail API: Config API

Access token Authorization

Requests sent to the Mail 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 Scaled Access. 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

Mail Config API

Get authorization config

Code samples

# You can also use wget
curl -X GET /tenants/{tenant}/email/authConfig \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /tenants/{tenant}/email/authConfig HTTP/1.1

Accept: application/json


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

fetch('/tenants/{tenant}/email/authConfig',
{
  method: 'GET',

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

GET /tenants/{tenant}/email/authConfig

Returns the authorization configuration (JWKS and JWT details).

Parameters

Name	In	Type	Required	Description
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {
    "jwksUri": "string",
    "issuer": "string",
    "audience": "string"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	AuthorizationConfigResponse

Update authorization config

Code samples

# You can also use wget
curl -X PUT /tenants/{tenant}/email/authConfig \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

PUT /tenants/{tenant}/email/authConfig HTTP/1.1

Content-Type: application/json
Accept: application/json

const inputBody = '{
  "jwksUri": "string",
  "issuer": "string",
  "audience": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/tenants/{tenant}/email/authConfig',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /tenants/{tenant}/email/authConfig

Updates the authorization configuration (JWKS and JWT details)

Body parameter

{
  "jwksUri": "string",
  "issuer": "string",
  "audience": "string"
}

Parameters

Name	In	Type	Required	Description
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"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	AuthorizationConfigResponse

Schemas

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"
  }
}

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.

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.

Mail API

Send invitation email

Code samples

# You can also use wget
curl -X POST /{tenant}/relationship-invitation \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST /{tenant}/relationship-invitation HTTP/1.1

Content-Type: application/json

const inputBody = '{
  "from": "string",
  "to": "string",
  "name": "string",
  "application": "string",
  "actionUrl": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/{tenant}/relationship-invitation',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /{tenant}/relationship-invitation

Sends an email to invite the receiver to a Relationship.

Body parameter

{
  "from": "string",
  "to": "string",
  "name": "string",
  "application": "string",
  "actionUrl": "string"
}

Parameters

Name	In	Type	Required	Description
tenant	path	string	true	Your tenant code.
body	body	SendRelationshipInvitationRequest	true	Details to send the mail.

Responses

Status	Meaning	Description	Schema
200	OK	When the receiver of the email follows the provided URL, the tenant must send a request to the Relationship Management API with the `requestToken` or `invitationId` to process the acceptance (Accept an Invitation). The Scaled Access customer can decide how to link these identifiers of the Invitation to the invited user, e.g. by adding them in the actionUrl.	None
400	Bad Request	none	None

Schemas

SendRelationshipInvitationRequest

{
  "from": "string",
  "to": "string",
  "name": "string",
  "application": "string",
  "actionUrl": "string"
}

Name	Type	Required	Restrictions	Description
from	string	true	none	The email address of the sender of the email. This must be a verified domain.
to	string	true	none	The email address of the receiver of the email.
name	string	true	none	The name to address the receiver of the email.
application	string	true	none	A human-readable name for the application to which the user is invited.
actionUrl	string	true	none	The URL to which the user will be redirected when accepting the invitation.

Event Stream

Overview and Concepts

Purpose

All meaningful events can be streamed to one of the tenant's API endpoints. The tenant can even configure what types of events will be streamed to which of their endpoints.

Content

The events that can be streamed are listed below per category. Note that GET requests are generally not considered meaningful and are therefore not streamed.

Consent Management: The audit log for user consents is stored separately and can currently not be streamed.
Relationship Management

Event	Properties
RELATIONSHIP_CREATED	`requestor.id`, `requestor.type`, `from.id`, `from.type`, `to.id`, `to.type`, `relationshipType`
RELATIONSHIPS_DELETED	`requestor.id`, `requestor.type`, `relationshipTypes`, `from.id`, `from.type`, `to.id`, `to.type`
INVITATION_CREATED	`requestor.id`, `requestor.type`, `target.id`, `target.type`, `invitor.id`, `invitor.type`, `invitationId`, `invitee.contact.type`, `invitee.contact.value`
INVITATION_ACCEPTED	`requestor.id`, `requestor.type`, `acceptor.id`, `acceptor.type`, `requestToken`, `invitationId`
INVITATION_WITHDRAWN	`requestor.id`, `requestor.type`, `revocator.id`, `revocator.type`, `invitationId`
USER_UPSERTED	`requestor.id`, `requestor.type`, `id`, `type` ("user")
USER_DELETED	`requestor.id`, `requestor.type`, `id`
RESOURCE_UPSERTED	`requestor.id`, `requestor.type`, `id`, `type`
RESOURCE_DELETED	`requestor.id`, `requestor.type`, `id`, `type`

Subscriptions

To set up the streaming of events, the tenant administrator must define a Subscription for a specific API endpoint that will receive the events.

The auth Attribute

We advise to protect the API endpoint with an authorization system, such as OAuth2. Details on how the Event Stream can request an access token for the endpoint via the OAuth2 Client Credentials grant type, can be included in the Subscription's auth.

Endpoints Overview

Endpoints:

Create a subscription
List all subscriptions
Get a subscription
Remove a subscription
Update a subscription

Event Stream API

Create a subscription

Code samples

# You can also use wget
curl -X POST /tenants/{tenant}/eventstream/subscriptions \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST /tenants/{tenant}/eventstream/subscriptions HTTP/1.1

Content-Type: application/json
Accept: application/json

const inputBody = '{
  "eventTypes": [
    "string"
  ],
  "maxPerSecond": 100,
  "numberOfRetries": 3,
  "auth": {
    "type": "string",
    "client": {
      "id": "string",
      "secret": "string"
    },
    "host": {
      "tokenHost": "string",
      "tokenPath": "string"
    },
    "scope": "string",
    "audience": "string"
  },
  "endpoint": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/tenants/{tenant}/eventstream/subscriptions',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /tenants/{tenant}/eventstream/subscriptions

Adds a subscription to the event stream.

Body parameter

{
  "eventTypes": [
    "string"
  ],
  "maxPerSecond": 100,
  "numberOfRetries": 3,
  "auth": {
    "type": "string",
    "client": {
      "id": "string",
      "secret": "string"
    },
    "host": {
      "tokenHost": "string",
      "tokenPath": "string"
    },
    "scope": "string",
    "audience": "string"
  },
  "endpoint": "string"
}

Parameters

Name	In	Type	Required	Description
tenant	path	string	true	Your tenant code.
body	body	AddEventStreamSubscriptionRequest	true	Details to add the subscription.

Example responses

200 Response

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {
    "endpoint": "string",
    "id": "string",
    "eventTypes": [
      "string"
    ],
    "maxPerSecond": 100,
    "numberOfRetries": 3,
    "auth": {
      "type": "string",
      "client": {
        "id": "string",
        "secret": "string"
      },
      "host": {
        "tokenHost": "string",
        "tokenPath": "string"
      },
      "scope": "string",
      "audience": "string"
    }
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	The subscription has been added succesfully.	SubscriptionResponse
400	Bad Request	A bad request could be caused by the wrong tenant code, the event stream feature not being enabled for the tenant, or trying to POST a subscription with an endpoint that is already subscribed. In case the endpoint has already been subscribed, use the PATCH operation instead.	None

List all subscriptions

Code samples

# You can also use wget
curl -X GET /tenants/{tenant}/eventstream/subscriptions \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /tenants/{tenant}/eventstream/subscriptions HTTP/1.1

Accept: application/json


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

fetch('/tenants/{tenant}/eventstream/subscriptions',
{
  method: 'GET',

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

GET /tenants/{tenant}/eventstream/subscriptions

Returns all existing subscriptions to the event stream.

Parameters

Name	In	Type	Required	Description
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": [
    {
      "endpoint": "string",
      "id": "string",
      "eventTypes": [
        "string"
      ],
      "maxPerSecond": 100,
      "numberOfRetries": 3,
      "auth": {
        "type": "string",
        "client": {
          "id": "string",
          "secret": "string"
        },
        "host": {
          "tokenHost": "string",
          "tokenPath": "string"
        },
        "scope": "string",
        "audience": "string"
      }
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	none	SubscriptionListResponse
400	Bad Request	A bad request could be caused by the wrong tenant code or the event stream feature not being enabled for the tenant.	None

Get a subscription

Code samples

# You can also use wget
curl -X GET /tenants/{tenant}/eventstream/subscriptions/{subscriptionId} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /tenants/{tenant}/eventstream/subscriptions/{subscriptionId} HTTP/1.1

Accept: application/json


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

fetch('/tenants/{tenant}/eventstream/subscriptions/{subscriptionId}',
{
  method: 'GET',

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

GET /tenants/{tenant}/eventstream/subscriptions/{subscriptionId}

Returns a specific subscription to the event stream.

Parameters

Name	In	Type	Required	Description
subscriptionId	path	string	true	The identifier of the subscription.
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {
    "endpoint": "string",
    "id": "string",
    "eventTypes": [
      "string"
    ],
    "maxPerSecond": 100,
    "numberOfRetries": 3,
    "auth": {
      "type": "string",
      "client": {
        "id": "string",
        "secret": "string"
      },
      "host": {
        "tokenHost": "string",
        "tokenPath": "string"
      },
      "scope": "string",
      "audience": "string"
    }
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	SubscriptionResponse
400	Bad Request	A bad request could be caused by the wrong tenant code, the event stream feature not being enabled for the tenant or the wrong subscription id.	None

Remove a subscription

Code samples

# You can also use wget
curl -X DELETE /tenants/{tenant}/eventstream/subscriptions/{subscriptionId} \
  -H 'Authorization: Bearer {access-token}'

DELETE /tenants/{tenant}/eventstream/subscriptions/{subscriptionId} HTTP/1.1


const headers = {
  'Authorization':'Bearer {access-token}'
};

fetch('/tenants/{tenant}/eventstream/subscriptions/{subscriptionId}',
{
  method: 'DELETE',

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

DELETE /tenants/{tenant}/eventstream/subscriptions/{subscriptionId}

Deletes a specific subscription to the event stream.

Parameters

Name	In	Type	Required	Description
subscriptionId	path	string	true	The identifier of the subscription.
tenant	path	string	true	Your tenant code.

Responses

Status	Meaning	Description	Schema
200	OK	The subscription was deleted.	None
400	Bad Request	A bad request could be caused by the wrong tenant code, the event stream feature not being enabled for the tenant or using the wrong subscription id.	None

Update a subscription

Code samples

# You can also use wget
curl -X PATCH /tenants/{tenant}/eventstream/subscriptions/{subscriptionId} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

PATCH /tenants/{tenant}/eventstream/subscriptions/{subscriptionId} HTTP/1.1

Content-Type: application/json
Accept: application/json

const inputBody = '{
  "eventTypes": [
    "string"
  ],
  "maxPerSecond": 100,
  "numberOfRetries": 3,
  "auth": {
    "type": "string",
    "client": {
      "id": "string",
      "secret": "string"
    },
    "host": {
      "tokenHost": "string",
      "tokenPath": "string"
    },
    "scope": "string",
    "audience": "string"
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/tenants/{tenant}/eventstream/subscriptions/{subscriptionId}',
{
  method: 'PATCH',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PATCH /tenants/{tenant}/eventstream/subscriptions/{subscriptionId}

Updates a subscription to the event stream.

Note:

The endpoint and subscriptionId cannot be updated.
With every update, all attributes of the Subscription are updated, either to the provided value or to the default value.

Body parameter

{
  "eventTypes": [
    "string"
  ],
  "maxPerSecond": 100,
  "numberOfRetries": 3,
  "auth": {
    "type": "string",
    "client": {
      "id": "string",
      "secret": "string"
    },
    "host": {
      "tokenHost": "string",
      "tokenPath": "string"
    },
    "scope": "string",
    "audience": "string"
  }
}

Parameters

Name	In	Type	Required	Description
subscriptionId	path	string	true	The identifier of the subscription.
tenant	path	string	true	Your tenant code.
body	body	UpdateEventStreamSubscriptionRequest	true	Details to update the subscription.

Example responses

200 Response

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {
    "endpoint": "string",
    "id": "string",
    "eventTypes": [
      "string"
    ],
    "maxPerSecond": 100,
    "numberOfRetries": 3,
    "auth": {
      "type": "string",
      "client": {
        "id": "string",
        "secret": "string"
      },
      "host": {
        "tokenHost": "string",
        "tokenPath": "string"
      },
      "scope": "string",
      "audience": "string"
    }
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	The subscription has been updated.	SubscriptionResponse
400	Bad Request	A bad request could be caused by the wrong tenant code, the event stream feature not being enabled for the tenant or using the wrong subscription id.	None

Schemas

OAuth2ConfigClient

{
  "id": "string",
  "secret": "string"
}

Name	Type	Required	Restrictions	Description
id	string	true	none	The client identifier.
secret	string	true	none	The client secret.

OAuth2ConfigHost

{
  "tokenHost": "string",
  "tokenPath": "string"
}

Name	Type	Required	Restrictions	Description
tokenHost	string	true	none	The URL of the host.
tokenPath	string	false	none	The host's endpoint to request an access token. By default, this value is set to '/oauth/token'.

OAuth2Config

{
  "type": "string",
  "client": {
    "id": "string",
    "secret": "string"
  },
  "host": {
    "tokenHost": "string",
    "tokenPath": "string"
  },
  "scope": "string",
  "audience": "string"
}

Name	Type	Required	Restrictions	Description
type	string	true	none	The type of authentication. This value must be `oauth2`.
client	OAuth2ConfigClient	true	none	none
host	OAuth2ConfigHost	true	none	none
scope	string	true	none	The scope that the client must request for the access token.
audience	string	true	none	The audience that the client must request for the access token.

AddEventStreamSubscriptionRequest

{
  "eventTypes": [
    "string"
  ],
  "maxPerSecond": 100,
  "numberOfRetries": 3,
  "auth": {
    "type": "string",
    "client": {
      "id": "string",
      "secret": "string"
    },
    "host": {
      "tokenHost": "string",
      "tokenPath": "string"
    },
    "scope": "string",
    "audience": "string"
  },
  "endpoint": "string"
}

Name	Type	Required	Restrictions	Description
eventTypes	[string]	false	none	The types of events that are streamed to the endpoint. By default all event types are streamed.
maxPerSecond	number	false	none	The maximum amount of requests that can be sent to the endpoint per second. By default there is no limit on the amount of requests (i.e. no throttling).
numberOfRetries	number	false	none	The number of times a failed request can be sent again. By default 3 times, i.e. a total of 4 attempts.
auth	OAuth2Config	false	none	none
endpoint	string	true	none	The endpoint to which events will be streamed. Only HTTPS endpoints are allowed.

SubscriptionConfig

{
  "endpoint": "string",
  "id": "string",
  "eventTypes": [
    "string"
  ],
  "maxPerSecond": 100,
  "numberOfRetries": 3,
  "auth": {
    "type": "string",
    "client": {
      "id": "string",
      "secret": "string"
    },
    "host": {
      "tokenHost": "string",
      "tokenPath": "string"
    },
    "scope": "string",
    "audience": "string"
  }
}

Name	Type	Required	Restrictions	Description
endpoint	string	true	none	The endpoint of the subscription where the events are sent to.
id	string	true	none	The identifier of the subscription.
eventTypes	[string]	false	none	The event types of the events that are sent to this subscription.
maxPerSecond	number	false	none	Defines how many events may be sent to the endpoint per second (i.e. throttling).
numberOfRetries	number	true	none	The number of times a failed request can be sent again. By default 3 times, i.e. a total of 4 attempts.
auth	OAuth2Config	false	none	none

SubscriptionResponse

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {
    "endpoint": "string",
    "id": "string",
    "eventTypes": [
      "string"
    ],
    "maxPerSecond": 100,
    "numberOfRetries": 3,
    "auth": {
      "type": "string",
      "client": {
        "id": "string",
        "secret": "string"
      },
      "host": {
        "tokenHost": "string",
        "tokenPath": "string"
      },
      "scope": "string",
      "audience": "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	SubscriptionConfig	false	none	The object describing the requested config.

SubscriptionListResponse

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": [
    {
      "endpoint": "string",
      "id": "string",
      "eventTypes": [
        "string"
      ],
      "maxPerSecond": 100,
      "numberOfRetries": 3,
      "auth": {
        "type": "string",
        "client": {
          "id": "string",
          "secret": "string"
        },
        "host": {
          "tokenHost": "string",
          "tokenPath": "string"
        },
        "scope": "string",
        "audience": "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	[SubscriptionConfig]	false	none	The object describing the requested config.

UpdateEventStreamSubscriptionRequest

{
  "eventTypes": [
    "string"
  ],
  "maxPerSecond": 100,
  "numberOfRetries": 3,
  "auth": {
    "type": "string",
    "client": {
      "id": "string",
      "secret": "string"
    },
    "host": {
      "tokenHost": "string",
      "tokenPath": "string"
    },
    "scope": "string",
    "audience": "string"
  }
}

Name	Type	Required	Restrictions	Description
eventTypes	[string]	false	none	The types of events that are streamed to the endpoint. By default all event types are streamed.
maxPerSecond	number	false	none	The maximum amount of requests that can be sent to the endpoint per second. By default there is no limit on the amount of requests (i.e. no throttling).
numberOfRetries	number	false	none	The number of times a failed request can be sent again. By default 3 times, i.e. a total of 4 attempts.
auth	OAuth2Config	false	none	none

Troubleshooting

Log records

All requests that arrive at the Scaled Access API's, together with the resulting events, are logged for 28 days. The log records can be used by the tenant for troubleshooting, e.g. to check whether a failed request arrived successfully at the API or to get more details about an error response.

Endpoint:

List log records

Logs API

List log records

Code samples

# You can also use wget
curl -X GET /tenants/{tenant}/logs \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /tenants/{tenant}/logs HTTP/1.1

Accept: application/json


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

fetch('/tenants/{tenant}/logs',
{
  method: 'GET',

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

GET /tenants/{tenant}/logs

Lists log records based on the specified filter criteria.

Parameters

Name	In	Type	Required	Description
start	query	string	false	A datetime (ISO-8601 format) to request the log records starting from a defined moment in time. `start` must lie before `end`. `start` cannot be combined with `last`.
end	query	string	false	A datetime (ISO-8601 format) to request the log records up to a defined moment in time. `start` must lie before `end`. `end` cannot be combined with `last`.
last	query	string	false	A duration (ISO-8601 format) to request the most recent log records for a defined period of time. `last` cannot be combined with `start` or `end`.
next	query	string	false	A token, obtained in a previous query, to request the next batch of records (pagination). This parameter can only be added if the previous query's response contained a `next` token. The other query parameters must be identical to the original request.
uuid	query	string	false	The identifier of a user to request the log records for that specific user.
accountIdentifier	query	string	false	A unique property of a user to request the log records for that specific user. The unique property can be an email address or phone number.
tenant	path	string	true	Your tenant code.

Example responses

200 Response

{
  "startTime": "string",
  "endTime": "string",
  "next": "string",
  "logs": [
    "string"
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	The number of records in one response is limited. If the number of records exceeds the limit, the `next` token will be present in the response. To obtain the next batch of log records, add the `next` parameter to the original request. Iterate the request until there is no longer a `next` token in the response.	LogResponse

Schemas

LogResponse

{
  "startTime": "string",
  "endTime": "string",
  "next": "string",
  "logs": [
    "string"
  ]
}

Name	Type	Required	Restrictions	Description
startTime	string	true	none	none
endTime	string	true	none	none
next	string	false	none	none
logs	[string]	false	none	none

Welcome

Onboarding

Getting started with Scaled Access

Scaled Access 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 an API

Step 2. Create an Application

Step 3. Add the Auth0 Rule

Obtaining and using an enriched access token

Step 4. Request an Auth0 access token

Step 5. 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 Rule

Obtaining an enriched access token in Postman

Step 4. Request an Auth0 access token

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 Scaled Access

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

Authorization Config API

List all Policies

Responses

Get a Policy

Parameters

Responses

Create/update Policy

Parameters

Responses

Delete a Policy

Parameters

Responses

Schemas

UpdatePolicyDataRequest

Authorization API

Authorize request

Parameters

Responses

Response Schema

Enumerated Values

Consent Enforcement

Overview and Concepts

About Consent Enforcement

Consent Enforcement with Scaled Access

Configuration of Consent Definitions: Config API

Information Model

Objects and Attributes

The Consent Objects

The optInConfig Attribute

The endOfLife Attribute

Custom Attributes

Active document versions and required user actions

Effective, Active, and Valid Documents

Updating user's consent

Example

Registration of User Consents: Consent Management API

Information Model

Authorization Rules

Access Management with User Consents: Authorization API

Policies

Endpoints Overview

Consent Config API