Portal Contact Support
Navigation
Shell HTTP JavaScript

Welcome

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

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:

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:

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.

  1. Log in at https://manage.scaledaccess.com with your personal username and password.
  2. Go to Settings and click Advanced Settings.
  3. Copy the displayed user access token. This token is valid for 24 hours.
  4. Place the access token in the Authorization Header of subsequent requests to the Config API:

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 \
  1. 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 (changes can be requested via support@scaledaccess.com or can be made by the administrator (only for the Relationship Management API)),
    • 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 (changes can be requested via support@scaledaccess.com or can be made by the administrator (only for the Relationship Management API)).
  2. 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
  1. 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.
  2. 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
  1. Go to Applications and click Create application.
  2. Select Machine to Machine Applications.
  3. Choose the API you created in the previous step.
  4. 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
        });
}

  1. In the Auth0 dashboard, go to (Auth pipelines >) Rules > Create Rule.
  2. In the next screen, choose Empty Rule.
  3. Choose a name for your rule.
  4. Copy the script on the right in the online editor and paste it on the Create Rule page.
  5. Click Save Changes.
  6. Click Back to Rules.
  7. 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.
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
  1. Use your regular method to request an access token.
  2. 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
  1. Use the enriched access token to access a protected resource at your API service.
  2. 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
  1. 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
  1. 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
  1. Start a new request.

  2. Go to the Authorization tab and select type OAuth 2.0.

  3. Click Get New Access Token. A new screen will open.

  4. 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
  5. 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:

  1. Authentication of the user: The user proves their identity, for example via their username and password.
  2. 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.
  3. 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:

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:

  1. Config API: Define customized policies.
  2. Authorization API: Take policies into account to make access 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 other Scaled Access APIs.

Access Management with Policies: Authorization API

Making Access Decisions

There are two levels of access control:

  1. Coarse-grained: Which actions is the user allowed to perform in the system? I.e. which qualifications does the user have?
  2. Fine-grained: Which of these actions is the user allowed to perform on a specific resource? I.e. which relationships does the user have and were the required consents given?

The customer's applications can make these decisions based on the access token send along with the user's request. However, what information is present in each access token depends on the configuration by the tenant and determines whether additional requests for tokens are required to access specific resources.

The token contains: Advantage
General token Role-based information about the authenticated user, e.g.
  • qualifications
Avoids heavy token payload.
Detailed token Role-based and attribute-based information about the authenticated user and resources (i.e. all the information necessary for the application to make its own decisions), e.g.
  • qualifications of the authenticated user,
  • relationships to specific resources, and
  • consents
No additional API calls are required.

Policy 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

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

Fetch a policy by name.

Parameters

Name In Type Required Description
policyName path string true none

Responses

Status Meaning Description Schema
200 OK none None

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

Upsert a policy

Body parameter

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

Parameters

Name In Type Required Description
policyName path string true none
body body UpdatePolicyDataRequest true none

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": {},
  "": "string"
}';
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": {},
  "": "string"
}

Parameters

Name In Type Required Description
body body object false none
» subject body object false The subject which is attempting the action.
»» id body string false none
»» type body string false Actor type, this will probably be 'user'
» action body string false Action to authorize. This is used to determine which policy is applicable
» resource body object false Resource on which the action is attempted. This can be any node (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 useful for the policy to determine its decision
tenant path string true none

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 none

anyOf

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

or

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

continued

Name Type Required Restrictions Description
» reason string false none none
» obligations [string] false none none

Enumerated Values

Property Value
anonymous allow
anonymous deny

Consent Enforcement

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:

  1. Config API: Define customized consents.
  2. Consent Management API: Register user consents and log each action with regard to these consents.
  3. Authorization API: Take user consents into account to make access 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:

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.

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.

Active document versions and required user actions

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:
    1. The ConsentDocument is active.
    2. The active ConsentDocument is located in the same ConsentVersion (i.e. the active document is only a minor update).
    3. 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. 
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.

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:

  1. 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.
  2. An audit-log (RegisterEvent) which stores all user requests and actions for audit purposes.

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

Policy rules

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 policy rules that are used to determine access rights. See the feature Externalized Authorization for more information on how to define these rules 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.

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:

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:

  1. Config API: Define and customize types of resources and relationships.
  2. Relationship Management API: Create and manage users, resources, and relationships.
  3. Authorization API: Take relationships into account to make access decisions.

Configuration of ActorTypes, ResourceTypes, and RelationshipTypes: Config API

Information Model

The Config API allows Scaled Access customers, called tenants, to define ActorTypes, ResourceTypes, and RelationshipTypes. These attributes of Actors, Resources, or Relationships are used by the Relationship Management API to:

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:

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:

To view or update the TokenMapping for your tenant, use the following endpoints:

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:

Access Management with Relationships: Authorization API

Policy rules

To fully profit from the relationship network created with the Relationship Management API, the tenant can design policy rules for their application based on the attributes of Actors, Resources, and Relationships. See Externalized Authorization for more information on how to define these rules 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": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "isActive"
        ],
        "properties": {
          "isActive": {
            "$id": "#/properties/isActive",
            "type": "boolean",
            "title": "Indicates if the relationship is still active"
          }
        }
      }
    }
  }
}

Responses

Status Meaning Description Schema
200 OK none RelationshipTypeResponse

Create/update a RelationshipType

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": {
    "schema": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "isActive"
      ],
      "properties": {
        "isActive": {
          "$id": "#/properties/isActive",
          "type": "boolean",
          "title": "Indicates if the relationship is still active"
        }
      }
    }
  }
}';
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.

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": {
    "schema": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "isActive"
      ],
      "properties": {
        "isActive": {
          "$id": "#/properties/isActive",
          "type": "boolean",
          "title": "Indicates if the relationship is still active"
        }
      }
    }
  }
}

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 Custom properties of the RelationshipType.
»» schema body object true A JSON schema defining custom attributes for the RelationshipType.

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

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": {
    "schema": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "chip_number"
      ],
      "properties": {
        "chip_number": {
          "$id": "#/properties/chip_number",
          "type": "string",
          "title": "The chip number",
          "examples": [
            "97373-928211-76"
          ]
        }
      }
    }
  }
}';
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": {
    "schema": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "chip_number"
      ],
      "properties": {
        "chip_number": {
          "$id": "#/properties/chip_number",
          "type": "string",
          "title": "The chip number",
          "examples": [
            "97373-928211-76"
          ]
        }
      }
    }
  }
}

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

Responses

Status Meaning Description Schema
200 OK none ActorTypeResponse

Create/update an ActorType

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": {
    "schema": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "birthdate"
      ],
      "properties": {
        "description": {
          "$id": "#/properties/birthdate",
          "type": "string",
          "title": "The birthdate",
          "examples": [
            "1983-09-28"
          ]
        }
      }
    }
  }
}';
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.

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

Body parameter

{
  "description": "User",
  "properties": {
    "schema": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "birthdate"
      ],
      "properties": {
        "description": {
          "$id": "#/properties/birthdate",
          "type": "string",
          "title": "The birthdate",
          "examples": [
            "1983-09-28"
          ]
        }
      }
    }
  }
}

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.

RelationshipTypeConfig

{
  "name": "string",
  "description": "string",
  "restrictions": [
    {
      "from": "string",
      "to": "string"
    }
  ],
  "properties": {
    "schema": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "isActive"
      ],
      "properties": {
        "isActive": {
          "$id": "#/properties/isActive",
          "type": "boolean",
          "title": "Indicates if the relationship is still active"
        }
      }
    }
  }
}

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 object false none A JSON schema defining custom attributes for the Relationship Type.

RelationshipTypeResponse

{
  "resources": [
    "string"
  ],
  "links": {},
  "config": {
    "name": "string",
    "description": "string",
    "restrictions": [
      {
        "from": "string",
        "to": "string"
      }
    ],
    "properties": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "isActive"
        ],
        "properties": {
          "isActive": {
            "$id": "#/properties/isActive",
            "type": "boolean",
            "title": "Indicates if the relationship is still active"
          }
        }
      }
    }
  }
}

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

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 object false none Custom properties of the ResourceType.
» schema object false none A JSON schema defining custom attributes for the ResourceType.

ResourceTypeResponse

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

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": {
    "schema": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "chip_number"
      ],
      "properties": {
        "chip_number": {
          "$id": "#/properties/chip_number",
          "type": "string",
          "title": "The chip number",
          "examples": [
            "97373-928211-76"
          ]
        }
      }
    }
  }
}

Name Type Required Restrictions Description
description object false none A human-readable description for the ResourceType.
properties object false none Custom properties of the ResourceType.
» schema object false none A JSON schema defining custom attributes for 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": {
    "schema": {}
  }
}

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 object false none Custom properties of the ActorType.
» schema object false none A JSON schema defining custom attributes for the ActorType.

ActorTypeResponse

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

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": {
    "schema": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "birthdate"
      ],
      "properties": {
        "description": {
          "$id": "#/properties/birthdate",
          "type": "string",
          "title": "The birthdate",
          "examples": [
            "1983-09-28"
          ]
        }
      }
    }
  }
}

Name Type Required Restrictions Description
description object false none A human-readable description for the ActorType.
properties object false none Custom properties of the ActorType.
» schema object false none A JSON schema defining custom attributes for 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.

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": "string",
  "customAttribute2": "boolean"
}';
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.

Body parameter

{
  "customAttribute1": "string",
  "customAttribute2": "boolean"
}

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.

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.

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",
  "from": {
    "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",
  "from": {
    "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.
» 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.

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

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

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",
  "from": {
    "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",
  "from": {
    "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.
» 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.

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

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

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

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": "string",
  "customAttribute2": "boolean"
}';
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": "string",
  "customAttribute2": "boolean"
}

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.

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.

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": "string",
  "customAttribute2": "boolean"
}';
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.

Body parameter

{
  "customAttribute1": "string",
  "customAttribute2": "boolean"
}

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.

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

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.

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",
  "from": {
    "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",
  "from": {
    "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.
» 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.

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

Delete Relationship(s)

Code samples

# You can also use wget
curl -X DELETE /{tenant}/actors/{actorType}/{actorId}/relationships?target%2Dtype=string&target%2Did=string&relationship%2Dtypes=string \
  -H 'Authorization: Bearer {access-token}'

DELETE /{tenant}/actors/{actorType}/{actorId}/relationships?target%2Dtype=string&target%2Did=string&relationship%2Dtypes=string HTTP/1.1


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

fetch('/{tenant}/actors/{actorType}/{actorId}/relationships?target%2Dtype=string&target%2Did=string&relationship%2Dtypes=string',
{
  method: 'DELETE',

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

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

Removes one or more Relationships between the Actor specified by {actorType} and {actorId} and the Actor/Resource specified with the query parameters target-id and target-type. The query parameter relationship-types is used to indicate which Relationship(s) must be removed.

Parameters

Name In Type Required Description
actorId path string true The identifier for the Actor.
actorType path string true The type of Actor.
target-type query string true The actorType or resourceType of the partner in the Relationship.
target-id query string true The actorId or resourceId of the partner in the Relationship.
relationship-types query string true A comma-separated list of the RelationshipType(s) to remove.
tenant path string true Your tenant code.

Responses

Status Meaning Description Schema
200 OK none None

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

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

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",
  "from": {
    "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",
  "from": {
    "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.
» 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.

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

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

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.

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

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.

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

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

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

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

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": "string",
  "customAttribute2": "boolean"
}';
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": "string",
  "customAttribute2": "boolean"
}

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.

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.

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": "string",
  "customAttribute2": "boolean"
}';
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.

Body parameter

{
  "customAttribute1": "string",
  "customAttribute2": "boolean"
}

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.

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

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.

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",
  "from": {
    "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",
  "from": {
    "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.
» 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.

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

Delete Relationship(s)

Code samples

# You can also use wget
curl -X DELETE /{tenant}/resources/{resourceType}/{resourceId}/relationships?target%2Dtype=string&target%2Did=string&relationship%2Dtypes=string \
  -H 'Authorization: Bearer {access-token}'

DELETE /{tenant}/resources/{resourceType}/{resourceId}/relationships?target%2Dtype=string&target%2Did=string&relationship%2Dtypes=string HTTP/1.1


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

fetch('/{tenant}/resources/{resourceType}/{resourceId}/relationships?target%2Dtype=string&target%2Did=string&relationship%2Dtypes=string',
{
  method: 'DELETE',

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

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

Removes one or more Relationships between the Resource specified by {resourceType} and {resourceId} and the Actor/Resource specified with the query parameters target-id and target-type. The query parameter relationship-types is used to indicate which Relationship(s) must be removed.

Parameters

Name In Type Required Description
resourceId path string true The identifier for the Resource.
resourceType path string true The type of Resource.
target-type query string true The actorType or resourceType of the partner in the Relationship.
target-id query string true The actorId or resourceId of the partner in the Relationship.
relationship-types query string true A comma-separated list of the RelationshipType(s) to remove.
tenant path string true Your tenant code.

Responses

Status Meaning Description Schema
200 OK none None

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

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

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",
  "from": {
    "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",
  "from": {
    "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.
» 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.

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

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.

  1. Request to verify your domain via support@scaledaccess.com.
  2. 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:

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.

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:

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:

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:

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
x Paste your access token here to see the code samples as you would use them in your application. Read about getting your access token here
vpn_key