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 our Authorization API or one of our trusted authorization servers, such as Auth0 and Okta. The access token must apply with the following:

    • the issuer and JWKS endpoint have been configured for your tenant,
    • the token signature algorithm is ES256 (ECDSA) or RS256 (RSA),
    • the sub claim is available, and
    • the aud claim is (one of) the allowed audience(s) as configured for your tenant.
  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 with to create 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 (e.g. 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 Okta

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

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

How to set up the Okta inline hook?

Okta setup

Step 1. Create a service application
  1. Log in to your Okta account.
  2. Go to Applications > Applications and click Add Application.
  3. Click Create New App.
  4. Select OAuth Service from the Platform dropdown menu.
  5. Click Create.
  6. Name your application, e.g. "Scaled Access Service App".
  7. Click Save.
Step 2. Create an inline hook
  1. Go to Workflow > Inline Hooks.
  2. Click Add Inline Hook and select Token from the dropdown menu.
  3. Enter the following values:
Field Name Value
Name Scaled Access
URL https://api.scaledaccess.com/okta/commands
Authentication field apiKey
Authentication secret The API key provided by Scaled Access. Contact support@scaledacces.com if you do not have an API key yet.
  1. Click Add Field to add the following key-value pairs:
Field Name Value
SCALED_ACCESS_CLIENTID The Client ID* of the "Scaled Access Service App" application created earlier.
SCALED_ACCESS_CLIENTSECRET The Client Secret* of the "Scaled Access Service App" 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). This code can be found in manage.scaledaccess.com after your sandbox environment is set up.

*The client credentials can be found by selecting the "Scaled Access Service App" in the Applications > Applications page.

  1. Click Save.
Step 3. Activate the inline hook
  1. Go to Security > API.
  2. Select the default Authorization Server.
  3. Click Edit.
  4. Go to the Scopes tab and click Add Scope.
    a. Enter pg:tenant:admin in the Name field.
    b. Click Create.
  5. Go to the Access Policies tab.
  6. For the Default Policy, edit the Default Policy Rule by clicking the pencil icon.
    a. In the Scopes requested field, select The following scopes:.
    b. Click OIDC default scopes to automatically fill in the required scopes.
    c. In the Use this inline hook field, select Scaled Access from the dropdown menu.
    d. Click Update Rule.
  7. For the Default Policy, click Add Rule.
    a. Enter "Scaled Access Service Rule" in the Name field.
    b. In the Scopes requested field, select The following scopes:.
    c. Enter pg:tenant:admin.
    d. Click Create Rule.

Obtaining and using an enriched access token

Step 4. Request an Okta access token
  1. Use your regular method to request an access token.
  2. Confirm that the access token contains the scaledaccess_relationships claim (e.g. by copying the token into jwt.io). If the user has no Relationships (yet), the array will be empty.
Step 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 scaledaccess_relationships claim.

Testing token enrichment in Postman

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

Okta setup

Step 1. Create a demo application
  1. Log in to your Okta account.
  2. Go to Applications > Applications and click Add Application.
  3. Click Create New App.
  4. Select Native Service from the Platform dropdown menu.
  5. Click Create.
  6. Name your application, e.g. "Scaled Access Demo".
  7. Click Add URI and enter a dummy URL, e.g. "http://localhost".
  8. Click Save.
  9. Edit the General Settings in the General tab.
    a. In the Allowed grant types field, check the Resource Owner Password checkbox.
    b. Click Save.
Step 2. Assign the demo application to a test user
  1. Go to Directory > People.
  2. Create a test user.
    a. click Add Person.
    b. Fill in the form. (For a test user, we recommend to select Set by admin from the Password dropdown menu and to deselect User must change password on first login.)
    c. Click Save.
  3. Select the test user.
  4. Click Assign Applications.
  5. Click Assign next to Scaled Access Demo.
  6. Click Save and Go Back.
  7. Click Done.

Obtaining an enriched access token in Postman

Step 3. Request an Okta access token
  1. Start a new request in Postman.
  2. Select POST and enter {issuer_uri}/v1/token in the URL field. The Issuer URI for the default Authorization Server can be found in the Security > API page.
  3. Got to the Body tab and select x-www-form-urlencoded.
  4. Enter the key-value pairs as shown below.
    Key Value
    grant_type password
    scope openid
    client_id The Client ID* of the "Scaled Access Demo" application.
    username The username of the user in step 2.
    password The password of the user in step 2.
    *The client credentials can be found by selecting the "Scaled Access Demo" in the Applications > Applications page.
  5. Click Send.
Step 4. Check the enriched token
  1. Copy the access token in the response.
  2. Paste the token in jwt.io.
  3. Confirm that the token contains the scaledaccess_relationships claim. If the user has no Relationships (yet), the array will be empty.

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

Configuration of Policies: Config API

Information Model

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

Objects and Attributes

Policy Name Attribute

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

The Rego Attribute and the Graphical Representation

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

Rego Example

rego: "

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

default outcome = "deny"

outcome = "allow" {
  user_is_admin_of_subscription
} 
{
  user_is_coadmin_of_subscription
}

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

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

Executing Policies: Authorization API

Information Model

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

To make an authorization request, use the following endpoint:

Endpoints Overview

Authorization Config API

List all Policies

Code samples

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

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


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

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

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

GET /tenants/{tenant}/policies

Lists all defined Policies.

Parameters

Name In Type Required Description
q query string false Optional search query param for filtering policies based on content.
tenant path string true Your tenant code.

Responses

Status Meaning Description Schema
200 OK none None

Get a Policy

Code samples

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

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

Accept: application/json


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

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

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

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

Returns a specific Policy.

Parameters

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

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK none PolicyRecordResponse

Create/update Policy

Code samples

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

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

Content-Type: application/json

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

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

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

Creates or updates a Policy.

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

Body parameter

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

Parameters

Name In Type Required Description
policyName path string true The identifier for the Policy.
tenant path string true Your tenant code.
body body UpdatePolicyDataRequest true none

Responses

Status Meaning Description Schema
200 OK none None

Delete a Policy

Code samples

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

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


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

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

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

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

Removes the Policy specified by {policyName}.

Parameters

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

Responses

Status Meaning Description Schema
200 OK none None

Schemas

PolicyRecordResponse

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

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

UpdatePolicyDataRequest

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

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

Authorization API

Authorize request

Code samples

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

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

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

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

POST /{tenant}

Make an authorization decision based on the configured policies.

Body parameter

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

Parameters

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

Example responses

200 Response

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

Responses

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

Response Schema

Status Code 200

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

Status Code 400

Name Type Required Restrictions Description
» message string false none none

Status Code 403

Name Type Required Restrictions Description
» message string false none none

Status Code 404

Name Type Required Restrictions Description
» message string false none none

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 (e.g. a company offering its services) must be able to demonstrate that the user consented to the processing of their personal data, i.e. the controller must register and keep track of its users' consents.

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

Information Model

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

Objects and Attributes

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

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

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

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

Access Management with User Consents: Authorization API

Policies

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

Endpoints Overview

List all ConsentDefinitions

Code samples

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

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

Accept: application/json


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

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

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

GET /tenants/{tenant}/consent-definitions

Lists all defined ConsentDefinitions.

Parameters

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

Example responses

200 Response

{
  "resources": [
    "string"
  ]
}

Responses

Status Meaning Description Schema
200 OK none ConsentDefinitionsResponse

Get ConsentDefinition

Code samples

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

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

Accept: application/json


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

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

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

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

Returns the ConsentDefinition specified by {name}.

Parameters

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

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK none ConsentDefinitionResponse

Create/update ConsentDefinition

Code samples

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

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

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

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

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

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

Creates or updates the ConsentDefinition specified by {name}.

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

Body parameter

{}

Parameters

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

Example responses

200 Response

{}

Responses

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

List all ConsentVersions

Code samples

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

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

Accept: application/json


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

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

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

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

Lists all ConsentVersions in ConsentDocument {name}.

Parameters

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

Example responses

200 Response

{
  "resources": [
    "string"
  ]
}

Responses

Status Meaning Description Schema
200 OK none ConsentVersionsResponse

Get ConsentVersion

Code samples

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

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

Accept: application/json


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

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

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

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

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

Parameters

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

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK none ConsentVersionResponse

Create/update ConsentVersion

Code samples

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

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

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

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

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

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

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

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

Body parameter

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

Parameters

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

Example responses

200 Response

{}

Responses

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

Get endOfLife of ConsentVersion

Code samples

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

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

Accept: application/json


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

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

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

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

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

Parameters

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

Example responses

200 Response

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

Responses

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

Create/update EndOfLife of ConsentVersion

Code samples

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

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

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

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

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

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

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

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

Body parameter

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

Parameters

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

Example responses

200 Response

{}

Responses

Status Meaning Description Schema
200 OK none EmptyResponse

List all ConsentDocument languages

Code samples

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

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

Accept: application/json


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

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

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

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

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

Parameters

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

Example responses

200 Response

{
  "resources": [
    "string"
  ]
}

Responses

Status Meaning Description Schema
200 OK none ConsentDocumentsLanguagesResponse

List all ConsentDocuments for one language

Code samples

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

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

Accept: application/json


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

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

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

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

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

Parameters

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

Example responses

200 Response

{
  "resources": [
    "string"
  ]
}

Responses

Status Meaning Description Schema
200 OK none ConsentDocumentsResponse

Get ConsentDocument

Code samples

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

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

Accept: application/json


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

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

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

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

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

Parameters

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

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK none ConsentDocumentResponse

Create/update ConsentDocument

Code samples

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

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

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

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

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

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

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

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

Body parameter

{
  "effectiveDate": "string"
}

Parameters

Name In Type Required Description
name path string true The identifier for the ConsentDefinition.
version path string true The identifier for the ConsentVersion..
language path string true The language (and/or other characteristics, such as country of residence) used to determine the audience for which the ConsentDocument applies. Each ConsentDocument only has one language.
documentVersion path string true An identifier for the ConsentDocument. The ConsentDocument is uniquely identified within the context of the ConsentVersion by the combination of language and documentVersion.
tenant path string true Your tenant code.
body body ConsentDocumentRequest true none

Example responses

200 Response

{}

Responses

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

ConsentDefinitionsResponse

{
  "resources": [
    "string"
  ]
}

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

ConsentDefinition

{
  "name": "string"
}

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

ConsentDefinitionResponse

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

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

ConsentDefinitionRequest

{}

None

EmptyResponse

{}

None

ConsentVersionsResponse

{
  "resources": [
    "string"
  ]
}

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

EndOfLifeRequest

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

Name Type Required Restrictions Description
startDate string true none A datetime (ISO-8601 format) indicating the first moment in time that users can receive notifications to report the termination of the associated ConsentVersion. This notification should include an invitation to accept the new version of the consent. startDate can only be set to a future moment in time and must lie before endDate.
endDate string true none A datetime (ISO-8601 format) indicating the last moment in time that a ConsentDocument of the associated ConsentVersion can be valid.
gracePeriod string true none A duration (ISO-8601 period format) indicating the period the user gets to agree to the new active ConsentDocument. This period starts the moment the user receives the first invitation to accept this new ConsentDocument. The actual grace period for a specific user will never extend passed the endDate.

ConsentVersion

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

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

ConsentVersionResponse

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

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

OptInConfigRequest

{
  "type": "direct"
}

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

ConsentVersionRequest

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

Name Type Required Restrictions Description
optInConfig OptInConfigRequest true none none

ConsentVersionEndOfLifeResponse

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

Name Type Required Restrictions Description
config EndOfLifeRequest true none none

ConsentDocumentsLanguagesResponse

{
  "resources": [
    "string"
  ]
}

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

ConsentDocumentsResponse

{
  "resources": [
    "string"
  ]
}

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

ConsentDocument

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

Name Type Required Restrictions Description
version string true none An identifier for the ConsentDocument. The ConsentDocument is uniquely identified within the context of the ConsentVersion by the combination of language and documentVersion.
language string true none The language (and/or other characteristics, such as country of residence) used to determine the audience for which the ConsentDocument applies. Each ConsentDocument only has one language.
effectiveDate string true none The moment in time at which the ConsentDocument can become effective and might replace a previous version (ISO-8601 dateTime format).

ConsentDocumentResponse

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

Name Type Required Restrictions Description
config ConsentDocument true none none

ConsentDocumentRequest

{
  "effectiveDate": "string"
}

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

Get the active ConsentDocument

Code samples

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

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

Accept: application/json


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

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

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

GET /{tenant}/consents/active

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

Parameters

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

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK none ConsentResponse

List my UserConsents

Code samples

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

GET /{tenant}/consents/me?filter=string HTTP/1.1

Accept: application/json


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

fetch('/{tenant}/consents/me?filter=string',
{
  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[string] 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}?filter=string \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /{tenant}/consents/{userId}?filter=string HTTP/1.1

Accept: application/json


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

fetch('/{tenant}/consents/{userId}?filter=string',
{
  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[string] 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 actors, resources, and relationships.
  2. Relationship Management API: Create and manage actors, resources, and relationships.
  3. Authorization API: Take relationships into account to make authorization decisions.

Configuration of the Domain Model: Config API

Information Model

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

Objects and Attributes

RelationshipType restrictions

Code example A: RelationshipType is_sibling_of

"restrictions":  [
  { "from": "user"; "to": "user" }
]

Code example B: RelationshipType is_owner_of

"restrictions":  [
  { "from": "user"; "to": "pet" }
  { "from": "user"; "to": "smart_lock" }
]

The restrictions object specifies a list of allowed ActorType/ResourceType combinations with a defined direction (from/to). When relationships are assigned with the Relationship Management API, these restrictions are taken into account for the requested RelationshipType.

Custom attributes

The properties attribute of the ActorTypes, ResourceTypes, and RelationshipTypes can be used to define additional (required or optional) attributes specific for the subset of objects. For example, the ResourceType pet can have the custom attributes external_identifier, birthdate, and chip_number.

Access token Authorization

Requests sent to the Relationship Management API must be accompanied by an access token issued by a trusted authorization server. To validate the token, the issuer and its JWKS endpoint must be known to 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

The policies specified for the Relationship Management API determine which actions actors can take on which objects. This can be based on attributes of the involved Actors, Resources, Relationships, and Invitations such as the type and relationship direction (from or to). These policies can be specified by the tenant admin (see Configuration of Policies).

New tenants are set up according to a blueprint specifying default policies for use of the Relationship Management API. These policies specify that:

Using Relationships in Authorization Decisions: Authorization API

Policies

To fully profit from the relationship network created with the Relationship Management API, the tenant can design policies for their application based on the attributes of Actors, Resources, and Relationships. See Externalized Authorization for more information on how to define and implement these policies for your application.

Endpoints Overview

Relationship Config API

Get TokenMapping

Code samples

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

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

Accept: application/json


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

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

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

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

Returns the TokenMapping configuration.

Parameters

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

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK none TokenMappingResponse

Update TokenMapping

Code samples

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

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

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

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

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

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

Updates the TokenMapping configuration.

Body parameter

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

Parameters

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

Example responses

200 Response

{}

Responses

Status Meaning Description Schema
200 OK none Inline

Response Schema

Get Authorization Config

Code samples

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

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

Accept: application/json


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

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

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

GET /tenants/{tenant}/groups/authConfig

Returns the authorization configuration (JWKS and JWT details).

Parameters

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

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK none AuthorizationConfigResponse

Update authorization config

Code samples

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

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

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

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

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

PUT /tenants/{tenant}/groups/authConfig

Updates the authorization configuration (JWKS and JWT details)

Body parameter

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

Parameters

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

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK none AuthorizationConfigResponse

> RelationshipType Endpoints

List all RelationshipTypes

Code samples

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

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

Accept: application/json


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

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

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

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

Lists all defined RelationshipTypes.

Parameters

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

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK none RelationshipTypeListResponse

Get a RelationshipType

Code samples

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

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

Accept: application/json


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

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

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

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

Returns a specific RelationshipType.

Parameters

Name In Type Required Description
relationshipType path string true The type of Relationship.
tenant path string true Your tenant code.

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK none RelationshipTypeResponse

Create/update a RelationshipType

Code samples

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

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

Content-Type: application/json

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

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

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

Creates or updates a RelationshipType. In addition, if the from type is an Actor, a default Policy of type {fromType}:{relationshipType}:{toType}:read is created, unless it already exists.

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

Body parameter

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

Parameters

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

Enumerated Values

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

Responses

Status Meaning Description Schema
200 OK none None

Delete RelationshipType

Code samples

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

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


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

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

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

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

Removes the specified RelationshipType.

Note: Data with this RelationshipType will NOT be erased.

Parameters

Name In Type Required Description
relationshipType path string true none
to query array true An ordered list of "to" restrictions that specify which restriction needs to be deleted.
from query array true An ordered list of "from" restrictions that specify which restriction needs to be deleted.

Detailed descriptions

to: An ordered list of "to" restrictions that specify which restriction needs to be deleted. The to value for each position combines with the from value in the same position to create a restriction.

e.g. ?from=a,b&to=c,d results in two restrictions being deleted: {from: "a", to: "c"} and {from: "b", to: "d"}

from: An ordered list of "from" restrictions that specify which restriction needs to be deleted. The from value for each position combines with the to value in the same position to create a restriction.

e.g. ?from=a,b&to=c,d results in two restrictions being deleted: {from: "a", to: "c"} and {from: "b", to: "d"}

Responses

Status Meaning Description Schema
204 No Content none None

> ResourceType Endpoints

List all ResourceTypes

Code samples

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

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

Accept: application/json


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

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

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

GET /tenants/{tenant}/groups/resources

Lists all defined ResourceTypes.

Parameters

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

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK none ResourceTypeListResponse

Get a ResourceType

Code samples

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

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

Accept: application/json


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

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

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

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

Returns a specific ResourceType.

Parameters

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

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK none ResourceTypeResponse

Create/update a ResourceType

Code samples

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

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

Content-Type: application/json

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

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

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

Creates or updates a ResourceType.

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

Body parameter

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

Parameters

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

Responses

Status Meaning Description Schema
200 OK none None

Delete ResourceType

Code samples

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

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


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

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

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

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

Removes the specified ResourceType.

Note: Data with this ResourceType will NOT be erased.

Parameters

Name In Type Required Description
resourceType path string true none

Responses

Status Meaning Description Schema
204 No Content none None

> ActorType Endpoints

List all ActorTypes

Code samples

# You can also use wget
curl -X GET /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 The type of Actor.
tenant path string true Your tenant code.

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK none 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": [
    {
      "name": "string",
      "type": "string"
    }
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Authorization':'Bearer {access-token}'
};

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

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

Creates or updates an ActorType. In addition, a default Policy of type {actorType}:read is created, unless it already exists.

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

Body parameter

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

Parameters

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

Responses

Status Meaning Description Schema
200 OK none None

Delete ActorType

Code samples

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

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


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

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

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

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

Removes the specified ActorType.

Note: Data with this ActorType will NOT be erased.

Parameters

Name In Type Required Description
actorType path string true none

Responses

Status Meaning Description Schema
204 No Content none None

> DomainModel Endpoints

Get domain model

Code samples

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

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

Accept: application/json


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

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

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

GET /tenants/{tenant}/groups/domain

Returns a the complete domain model.

Parameters

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

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK none DomainModelResponse

Schemas

RelationshipTypeListResponse

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

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

Restriction

{
  "from": "string",
  "to": "string"
}

Name Type Required Restrictions Description
from string true none The ActorType or ResourceType from which the Relationship can start.
to string true none The ActorType or ResourceType at which the Relationship can end.

ElementTypeProperty

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

Name Type Required Restrictions Description
name string true none The name of the property. Only alphanumeric characters and underscores are allowed.
type string true none The data type of the property. The allowed values are string, number, boolean, and date.
Enumerated Values
Property Value
type string
type number
type boolean
type date

RelationshipTypeConfig

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

Name Type Required Restrictions Description
name string true none The name of the RelationshipType.
description string false none A human-readable description for the RelationshipType.
restrictions [Restriction] true none none
properties [ElementTypeProperty] false none Custom attributes for the Relationship Type.

RelationshipTypeResponse

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

Name Type Required Restrictions Description
resources [string] true none A list of all child resources currently existing in this endpoint.
links object true none The URI's of the linked resources.
config RelationshipTypeConfig false none The object describing the requested config.

TokenMapping

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

Name Type Required Restrictions Description
actorIdClaimPath string true none The path to the claim in the access token which represents the userId of the authenticated User.
actorTypeClaimPath string true none The path to the claim in the access token which represents the userType of the authenticated User.

TokenMappingResponse

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

Name Type Required Restrictions Description
resources [string] true none A list of all child resources currently existing in this endpoint.
links object true none The URI's of the linked resources.
config TokenMapping false none The object describing the requested config.

SaveTokenMappingRequest

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

Name Type Required Restrictions Description
actorIdClaimPath string true none The path to the claim in the access token which represents the userId of the authenticated User.
actorTypeClaimPath string true none The path to the claim in the access token which represents the userType of the authenticated User.

ResourceTypeListResponse

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

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

ResourceTypeConfig

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

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

ResourceTypeResponse

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

Name Type Required Restrictions Description
resources [string] true none A list of all child resources currently existing in this endpoint.
links object true none The URI's of the linked resources.
config ResourceTypeConfig false none The object describing the requested config.

SaveResourceTypeRequest

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

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

ActorTypeListResponse

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

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

ActorTypeConfig

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

Name Type Required Restrictions Description
name string true none The name of the ActorType.
description string true none A human-readable description for the ActorType.
properties [ElementTypeProperty] false none Custom properties of the ActorType.

ActorTypeResponse

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

Name Type Required Restrictions Description
resources [string] true none A list of all child resources currently existing in this endpoint.
links object true none The URI's of the linked resources.
config ActorTypeConfig false none The object describing the requested config.

SaveActorTypeRequest

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

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

AuthorizationConfig

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

Name Type Required Restrictions Description
jwksUri string true none The URI of the JSON Web Key Set.
issuer string true none The URI of the JWT issuer.
audience string false none The expected audience of the JWT.

AuthorizationConfigResponse

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

Name Type Required Restrictions Description
resources [string] true none A list of all child resources currently existing in this endpoint.
links object true none The URI's of the linked resources.
config AuthorizationConfig false none The object describing the requested config.

AuthorizationConfigRequest

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

Name Type Required Restrictions Description
jwksUri string true none The URI of the JSON Web Key Set.
issuer string true none The URI of the JWT issuer.
audience string false none The expected audience of the JWT.

DomainModelResponse

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

Name Type Required Restrictions Description
resourceTypes [ResourceTypeConfig] false none ResourceTypes
actorTypes [ActorTypeConfig] false none ActorTypes
relationshipTypes [RelationshipTypeConfig] false none RelationshipTypes

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.

Authorization request template

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

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${principal.nodeType}:read) by using the Authorization Config API.

Create/update my Actor

Code samples

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

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

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

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

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

PUT /{tenant}/actors/me

Creates or updates the Actor authenticated by the user access token.

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

Note 2: If the Actor does not exist yet, the {actorType}:create Policy will be evaluated. Otherwise, the {actorType}:update Policy will be evaluated.

Body parameter

{
  "customAttribute1": "value1",
  "customAttribute2": "value2"
}

Parameters

Name In Type Required Description
tenant path string true Your tenant code.
body body object true An object specifying custom attributes for the Actor. This object must follow the JSON schema defined for ActorType.

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK none Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» id string true none The identifier of the Actor.
» type string true none The type of the Actor.
» customAttribute any false none A property defined by the tenant for this type of object.

Authorization request template

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

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${principal.nodeType}:<createOrUpdate>) by using the Authorization Config API.

List my Relationships

Code samples

# You can also use wget
curl -X GET /{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 [RelationshipDetailResponse] false none none
» id string true none The identifier for the Relationship.
» relationshipType string true none The type of Relationship between the from and to Actor(s)/Resource(s).
» from NodeDetailResponse true none none
»» id string true none The identifier of the Actor/Resource.
»» type string true none The actorType or resourceType of the Actor/Resource.
» to NodeDetailResponse true none none
» properties object false none The custom properties of the Relationship.

Authorization request template

{
  "action": "${principal.nodeType}:relationships:list",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "relationshipTypes": "${query[\"relationship-types\"]}",
    "direction": "${query[\"direction\"]}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${principal.nodeType}:relationships:list) by using the Authorization Config API.

Create my Relationship

Code samples

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

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

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

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

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

POST /{tenant}/actors/me/relationships

Creates a Relationship from the Actor authenticated by the user access token to the target specified in the body.

Body parameter

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

Parameters

Name In Type Required Description
tenant path string true Your tenant code.
body body object true none
» relationshipType body string true The type of relationship.
» to body object true The target Actor/Resource in the Relationship.
» properties body object false The custom properties as defined in the relationship type.

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK none RelationshipDetailResponse

Authorization request template

{
  "action": "${principal.nodeType}:${body.relationshipType}:${body.to.type}:create",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${principal.nodeId}",
      "type": "${principal.nodeType}"
    },
    "to": {
      "id": "${body.to.id}",
      "type": "${body.to.type}"
    },
    "relationshipType": "${body.relationshipType}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${principal.nodeType}:${body.relationshipType}:${body.to.type}:create) by using the Authorization Config API.

Get my Relationship

Code samples

# You can also use wget
curl -X GET /{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

Authorization request template

{
  "action": "${principal.nodeType}:<relationshipType>:<targetType>:read",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${principal.nodeId}",
      "type": "${principal.nodeType}"
    },
    "relationshipId": "${params.relationshipId}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${principal.nodeType}:<relationshipType>:<targetType>:read) by using the Authorization Config API.

Update my Relationship

Code samples

# You can also use wget
curl -X PUT /{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 = '{
  "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

{
  "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
» properties body object true The custom properties as defined in the relationship type.

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK none RelationshipDetailResponse

Authorization request template

{
  "action": "${principal.nodeType}:<relationshipType>:<targetType>:update",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${principal.nodeId}",
      "type": "${principal.nodeType}"
    },
    "to": {
      "id": "<targetId>",
      "type": "<targetType>"
    },
    "relationshipType": "<relationshipType>",
    "relationshipId": "${params.relationshipId}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${principal.nodeType}:<relationshipType>:<targetType>:update) by using the Authorization Config API.

Delete my Relationship

Code samples

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

DELETE /{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: '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.

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

Authorization request template

{
  "action": "${principal.nodeType}:<relationshipType>:<targetType>:delete",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${principal.nodeId}",
      "type": "${principal.nodeType}"
    },
    "to": {
      "id": "<targetId>",
      "type": "<targetType>"
    },
    "relationshipType": "<relationshipType>",
    "relationshipId": "${params.relationshipId}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${principal.nodeType}:<relationshipType>:<targetType>:delete) by using the Authorization Config API.

> Actor Endpoints

List all Actors of type

Code samples

# You can also use wget
curl -X GET /{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.

Authorization request template

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

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.actorType}:list) by using the Authorization Config API.

Create an Actor

Code samples

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

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

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

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

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

POST /{tenant}/actors/{actorType}

Creates an Actor of type {actorType}. The system will assign an actorId.

Body parameter

{
  "customAttribute1": "value1",
  "customAttribute2": "value2"
}

Parameters

Name In Type Required Description
actorType path string true The type of Actor.
tenant path string true Your tenant code.
body body object true An object specifying custom attributes for the Actor. This object must follow the JSON schema defined for the chosen ActorType.

Example responses

201 Response

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

Responses

Status Meaning Description Schema
201 Created none Inline

Response Schema

Status Code 201

Name Type Required Restrictions Description
» id string true none The identifier of the Actor.
» type string true none The type of the Actor.
» customAttribute any false none A property defined by the tenant for this type of object.

Authorization request template

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

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.actorType}:create) by using the Authorization Config API.

Get an Actor

Code samples

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

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

Accept: application/json


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

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

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

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

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

Parameters

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

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK none Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» id string true none The identifier of the Actor.
» type string true none The type of the Actor.
» customAttribute any false none A property defined by the tenant for this type of object.

Authorization request template

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

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.actorType}:read) by using the Authorization Config API.

Create/update an Actor

Code samples

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

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

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

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

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

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

Creates or updates the Actor specified by {actorType} and {actorId}.

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

Note 2: If the Actor does not exist yet, the {actorType}:create Policy will be evaluated. Otherwise, the {actorType}:update Policy will be evaluated.

Body parameter

{
  "customAttribute1": "value1",
  "customAttribute2": "value2"
}

Parameters

Name In Type Required Description
actorType path string true The type of Actor.
actorId path string true The identifier for the Actor.
tenant path string true Your tenant code.
body body object true An object specifying custom attributes for the Actor. This object must follow the JSON schema defined for the chosen ActorType.

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK none Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» id string true none The identifier of the Actor.
» type string true none The type of the Actor.
» customAttribute any false none A property defined by the tenant for this type of object.

Authorization request template

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

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.actorType}:<createOrUpdate>) by using the Authorization Config API.

Delete an Actor

Code samples

# You can also use wget
curl -X DELETE /{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

Authorization request template

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

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.actorType}:delete) by using the Authorization Config API.

List all Relationships

Code samples

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

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

Accept: application/json


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

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

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

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

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

Parameters

Name In Type Required Description
actorType path string true The type of Actor.
actorId path string true The identifier for the Actor.
signed query boolean false Optional signing of Relationships. If true, the response will contain signed Relationships. The default value is false; the response contains human-readable objects.
all query boolean false Optional inclusion of reserved RelationshipTypes. If true, the response will include the RelationshipTypes predefined by Scaled Access. The default value is false.
direction query string false Optional direction (from or to) of the Relationship with respect to the Actor specified by {actorType} and {actorId}.
relationship-types query string false Optional comma-separated list of RelationshipTypes to filter on.
tenant path string true Your tenant code.

Enumerated Values

Parameter Value
direction from
direction to

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK none Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
anonymous [RelationshipDetailResponse] false none none
» id string true none The identifier for the Relationship.
» relationshipType string true none The type of Relationship between the from and to Actor(s)/Resource(s).
» from NodeDetailResponse true none none
»» id string true none The identifier of the Actor/Resource.
»» type string true none The actorType or resourceType of the Actor/Resource.
» to NodeDetailResponse true none none
» properties object false none The custom properties of the Relationship.

Authorization request template

{
  "action": "${params.actorType}:relationships:list",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${params.actorId}",
    "type": "${params.actorType}",
    "relationshipTypes": "${query[\"relationship-types\"]}",
    "direction": "${query[\"direction\"]}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.actorType}:relationships:list) by using the Authorization Config API.

Create a Relationship

Code samples

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

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

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

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

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

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

Creates a Relationship from the Actor specified by {actorType} and {actorId} to the target specified in the body.

Body parameter

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

Parameters

Name In Type Required Description
actorType path string true The type of Actor.
actorId path string true The identifier for the Actor.
tenant path string true Your tenant code.
body body object true none
» relationshipType body string true The type of relationship.
» to body object true The target Actor/Resource in the Relationship.
» properties body object false The custom properties as defined in the relationship type.

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK none RelationshipDetailResponse

Authorization request template

{
  "action": "${params.actorType}:${body.relationshipType}:${body.to.type}:create",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${params.actorId}",
      "type": "${params.actorType}"
    },
    "to": {
      "id": "${body.to.id}",
      "type": "${body.to.type}"
    },
    "relationshipType": "${body.relationshipType}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.actorType}:${body.relationshipType}:${body.to.type}:create) by using the Authorization Config API.

Delete a Relationship

Code samples

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

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

Accept: application/json


const headers = {
  'Accept':'application/json',
  '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.

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

Authorization request template

{
  "action": "${params.actorType}:<relationshipType>:<targetType>:delete",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${params.actorId}",
      "type": "${params.actorType}"
    },
    "to": {
      "id": "<targetId>",
      "type": "<targetType>"
    },
    "relationshipType": "<relationshipType>",
    "relationshipId": "${params.relationshipId}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.actorType}:<relationshipType>:<targetType>:delete) by using the Authorization Config API.

Get a Relationship

Code samples

# You can also use wget
curl -X GET /{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

Authorization request template

{
  "action": "${params.actorType}:<relationshipType>:<targetType>:read",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${params.actorId}",
      "type": "${params.actorType}"
    },
    "to": {
      "id": "<targetId>",
      "type": "<targetType>"
    },
    "relationshipType": "<relationshipType>",
    "relationshipId": "${params.relationshipId}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.actorType}:<relationshipType>:<targetType>:read) by using the Authorization Config API.

Update a Relationship

Code samples

# You can also use wget
curl -X PUT /{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 = '{
  "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

{
  "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
» properties body object true The custom properties as defined in the relationship type.

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK none RelationshipDetailResponse

Authorization request template

{
  "action": "${params.actorType}:<relationshipType>:<targetType>:update",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${params.actorId}",
      "type": "${params.actorType}"
    },
    "to": {
      "id": "<targetId>",
      "type": "<targetType>"
    },
    "relationshipType": "<relationshipType>",
    "relationshipId": "${params.relationshipId}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.actorType}:<relationshipType>:<targetType>:update) by using the Authorization Config API.

> Invitation Endpoints

List my Invitations

Code samples

# You can also use wget
curl -X GET /{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",
    "expiryDate": 1613554476,
    "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 invitee and the target.
» relationshipDirectionForSubject string true none The role suggested for the subject, i.e. the invitee, in the Relationship. The Relationship can start from (from) or end at (to) the subject.
» expiryDate number true none The expiry date of the invitation, as a unix timestamp in seconds.
» inviteeContactType string false none The type of contact information available for the invitee.
» inviteeContactValue string false none The contact information of the invitee.
» isCreatedBy object false none The Actor that requested the invitation.
» 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.

Authorization request template

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

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case invitation:list) by using the Authorization Config API.

List all Invitations

Code samples

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

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

Accept: application/json


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

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

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

GET /{tenant}/sharing/invitations

Lists all Invitations linked to the Actor or Resource specified by the query parameters {id} and {type}.

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",
    "expiryDate": 1613554476,
    "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 invitee and the target.
» relationshipDirectionForSubject string true none The role suggested for the subject, i.e. the invitee, in the Relationship. The Relationship can start from (from) or end at (to) the subject.
» expiryDate number true none The expiry date of the invitation, as a unix timestamp in seconds.
» inviteeContactType string false none The type of contact information available for the invitee.
» inviteeContactValue string false none The contact information of the invitee.
» isCreatedBy object false none The Actor that requested the invitation.
» 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.

Authorization request template

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

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case invitation:list) by using the Authorization Config API.

Create an Invitation

Code samples

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

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

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

const inputBody = '{
  "relationshipType": "string",
  "to": {
    "id": "string",
    "type": "string"
  },
  "invitor": {
    "id": "string",
    "type": "string"
  },
  "invitee": {
    "contact": {
      "type": "email",
      "value": "string"
    }
  },
  "expiryDate": 1613485553
}';
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"
    }
  },
  "expiryDate": 1613485553
}

Parameters

Name In Type Required Description
body body object true none
» relationshipType body string true The type of relationship suggested for the invitee and the target.
» from body object false The target Actor/Resource in the Relationship. Choose from or to to indicate the direction of the Relationship.
» to body object false The target Actor/Resource in the Relationship. Choose from or to to indicate the direction of the Relationship.
» invitor body object false The Actor who requests the invitation. If not provided, the subject from the access token will be used as Actor (if a subject is present).
» invitee body object false The actor who is invited to form a Relationship.
»» contact body object false Contact information.
»»» type body string true The type of contact information. This value must be set to email.
»»» value body string true An email address.
» expiryDate body number false An expiry date as unix timestamp in seconds. If not provided, the expiry date will be set 24 hours in the future.

Enumerated Values

Parameter Value
»»» type email

Example responses

201 Response

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

Responses

Status Meaning Description Schema
201 Created The Invitation is created. The invitationId or requestToken in the response body can be used by the client in a subsequent request to the Relationship Management API to accept the invitation on request of the invitee. The Relationship Management API will validate whether a provided requestToken is still valid, whereas it will accept an invitationId without validation. CreateInvitationResponse

Authorization request template

{
  "action": "${!!body.from ? body.from.type : 'user'}:${body.relationshipType}:${!!body.from ? 'user' : body.to.type}:invitation:create",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${!!body.from ? body.from.id : ''}",
      "type": "${!!body.from ? body.from.type : 'user'}"
    },
    "to": {
      "id": "${!!body.to ? body.to.id : ''}",
      "type": "${!!body.to ? body.to.type : 'user'}"
    },
    "direction": "${!!body.from ? \"from\" : \"to\"}",
    "invitor": {
      "id": "${body.invitor && body.invitor.id || principal.nodeId}",
      "type": "${body.invitor && body.invitor.type || principal.nodeType}"
    },
    "relationshipType": "${body.relationshipType}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${!!body.from ? body.from.type : 'user'}:${body.relationshipType}:${!!body.from ? 'user' : body.to.type}:invitation:create) by using the Authorization Config API.

Get an invitation

Code samples

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

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

Accept: application/json


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

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

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

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

Returns the Invitation specified by {invitationId}.

Parameters

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

Example responses

200 Response

{
  "id": "string",
  "type": "invitation",
  "relationshipType": "string",
  "relationshipDirectionForSubject": "from",
  "expiryDate": 1613554331,
  "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 invitee and the target.
» relationshipDirectionForSubject string true none The role suggested for the subject, i.e. the invitee, in the Relationship. The Relationship can start from (from) or end at (to) the subject.
» expiryDate number true none The expiry date of the invitation, as a unix timestamp in seconds.
» inviteeContactType string false none The type of contact information available for the invitee.
» inviteeContactValue string false none The contact information of the invitee.
» isCreatedBy object false none The Actor that requested the invitation.
» 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.

Authorization request template

{
  "action": "<relationshipSourceType>:<relationshipType>:<relationshipTargetType>:invitation:read",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${params.invitationId}",
    "type": "invitation"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case <relationshipSourceType>:<relationshipType>:<relationshipTargetType>:invitation:read) by using the Authorization Config API.

Refresh an Invitation

Code samples

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

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

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

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

fetch('/{tenant}/sharing/invitations/{invitationId}',
{
  method: 'PUT',
  body: inputBody,
  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.

Body parameter

{
  "expiryDate": 0
}

Parameters

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

Example responses

201 Response

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

Responses

Status Meaning Description Schema
201 Created The Invitation is refreshed. The invitationId or requestToken in the response body can be used by the client in a subsequent request to the Relationship Management API to accept the invitation on request of the invitee. The Relationship Management API will validate whether a provided requestToken is still valid, whereas it will accept an invitationId without validation. CreateInvitationResponse

Authorization request template

{
  "action": "<relationshipSourceType>:<relationshipType>:<relationshipTargetType>:invitation:refresh",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${params.invitationId}",
    "type": "invitation"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case <relationshipSourceType>:<relationshipType>:<relationshipTargetType>:invitation:refresh) by using the Authorization Config API.

Accept an Invitation

Code samples

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

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

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

const inputBody = '{
  "acceptor": {
    "id": "string",
    "type": "string"
  },
  "requestToken": "string",
  "properties": {
    "isActive": "true"
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'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.

Example responses

200 Response

{
  "id": "string",
  "type": "invitation",
  "relationshipType": "string",
  "relationshipDirectionForSubject": "from",
  "expiryDate": 1613554331,
  "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 invitee and the target.
» relationshipDirectionForSubject string true none The role suggested for the subject, i.e. the invitee, in the Relationship. The Relationship can start from (from) or end at (to) the subject.
» expiryDate number true none The expiry date of the invitation, as a unix timestamp in seconds.
» inviteeContactType string false none The type of contact information available for the invitee.
» inviteeContactValue string false none The contact information of the invitee.
» isCreatedBy object false none The Actor that requested the invitation.
» 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.

Authorization request template

{
  "action": "invitation:accept",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${body.acceptor && body.acceptor.id || accessToken.nodeId}",
    "type": "${body.acceptor && body.acceptor.type || accessToken.nodeType}",
    "invitationId": "${body.invitationId}",
    "requestToken": "${body.requestToken || undefined}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case invitation:accept) by using the Authorization Config API.

Withdraw an Invitation

Code samples

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

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

Content-Type: application/json

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

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

POST /{tenant}/sharing/invitations/withdraw

Withdraws an Invitation.

Body parameter

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

Parameters

Name In Type Required Description
tenant path string true Your tenant code.
body body object true none
» revocator body object false The Actor withdrawing the invitation. If not provided, the subject from the access token will be used as Actor.
»» id body string true The identifier of the Actor.
»» type body string true The type of Actor.
» invitationId body string true The identifier of the Invitation.

Responses

Status Meaning Description Schema
200 OK The invitee can no longer accept the Invitation. None

Authorization request template

{
  "action": "<relationshipSourceType>:<relationshipType>:<relationshipTargetType>:invitation:withdraw",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${body.invitationId}",
    "type": "invitation"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case <relationshipSourceType>:<relationshipType>:<relationshipTargetType>:invitation:withdraw) by using the Authorization Config API.

> Approval Request Endpoints

List my approval requests

Code samples

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

GET /{tenant}/sharing/approval-requests/me HTTP/1.1

Accept: application/json


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

fetch('/{tenant}/sharing/approval-requests/me',
{
  method: 'GET',

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

GET /{tenant}/sharing/approval-requests/me

Lists all Approval Requests linked to 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": "123",
    "type": "approvalrequest",
    "relationshipType": "is_member_of",
    "approvalRequestType": "relationship",
    "from": {
      "id": "user1",
      "type": "user"
    },
    "to": {
      "id": "user2",
      "type": "user"
    },
    "initiates": {
      "id": "user3",
      "type": "user"
    }
  }
]

Responses

Status Meaning Description Schema
200 OK none Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» id string true none The identifier for the Approval Request.
» type string true none The type of object, an Approval Request.
» relationshipType string true none The type of relationship to be created once the approval request is approved.
» approvalRequestType string true none The type of approval request.
» from object false none The target associated with the approval request's relationship origin
»» id string false none none
»» type string false none none
» to object false none The target associated with the approval request's relationship target
»» id string false none none
»» type string false none none
» approves object false none The Actor that approves the Approval Request.
»» id string false none none
»» type string false none none
» denies object false none The Actor that denies the Approval Request.
»» id string false none none
»» type string false none none
» initiates object false none The Actor that initiated the Approval Request
»» id string false none none
»» type string false none none

Authorization request template

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

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case approvalrequest:list) by using the Authorization Config API.

List all Approval Requests

Code samples

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

GET /{tenant}/sharing/approval-requests?id=string&type=string HTTP/1.1

Accept: application/json


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

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

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

GET /{tenant}/sharing/approval-requests

Lists all Approval Requests linked to the Actor or Resource specified by the query parameters {id} and {type}.

Parameters

Name In Type Required Description
id query string true The actorId or resourceId of the Actor/Resource for which to find Approval Requests.
type query string true The actorType or resourceType of the Actor/Resource for which to find Approval Requests.
tenant path string true Your tenant code.

Example responses

200 Response

[
  {
    "id": "123",
    "type": "approvalrequest",
    "relationshipType": "is_member_of",
    "approvalRequestType": "relationship",
    "from": {
      "id": "user1",
      "type": "user"
    },
    "to": {
      "id": "user2",
      "type": "user"
    },
    "initiates": {
      "id": "user3",
      "type": "user"
    }
  }
]

Responses

Status Meaning Description Schema
200 OK none Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» id string true none The identifier for the Approval Request.
» type string true none The type of object, an Approval Request.
» relationshipType string true none The type of relationship to be created once the approval request is approved.
» approvalRequestType string true none The type of approval request.
» from object false none The target associated with the approval request's relationship origin
»» id string false none none
»» type string false none none
» to object false none The target associated with the approval request's relationship target
»» id string false none none
»» type string false none none
» approves object false none The Actor that approves the Approval Request.
»» id string false none none
»» type string false none none
» denies object false none The Actor that denies the Approval Request.
»» id string false none none
»» type string false none none
» initiates object false none The Actor that initiated the Approval Request
»» id string false none none
»» type string false none none

Authorization request template

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

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case approvalrequest:list) by using the Authorization Config API.

Create an Approval Request

Code samples

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

POST /{tenant}/sharing/approval-requests HTTP/1.1

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

const inputBody = '{
  "approvalRequestType": "relationship",
  "relationshipType": "string",
  "from": {
    "id": "string",
    "type": "string"
  },
  "to": {
    "id": "string",
    "type": "string"
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

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

POST /{tenant}/sharing/approval-requests

Creates an Approval Request to form a Relationship between the the given actors/resources

Body parameter

{
  "approvalRequestType": "relationship",
  "relationshipType": "string",
  "from": {
    "id": "string",
    "type": "string"
  },
  "to": {
    "id": "string",
    "type": "string"
  }
}

Parameters

Name In Type Required Description
body body CreateApprovalRequestRequest true none

Example responses

201 Response

{
  "approvalRequestId": "string"
}

Responses

Status Meaning Description Schema
201 Created The Approval Request is created. The approvalRequestId in the response body can be used by the client in a subsequent request to the Relationship Management API to approve the approval request. CreateApprovalRequestResponse

Authorization request template

{
  "action": "${body.from.type}:${body.relationshipType}:${body.to.type}:approvalrequest:create",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${body.from.id}",
      "type": "${body.from.type}"
    },
    "to": {
      "id": "${body.to.id}",
      "type": "${body.to.type}"
    },
    "initiator": {
      "id": "${principal.nodeId}",
      "type": "${principal.nodeType}"
    },
    "relationshipType": "${body.relationshipType}",
    "approvalRequestType": "${body.approvalRequestType}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${body.from.type}:${body.relationshipType}:${body.to.type}:approvalrequest:create) by using the Authorization Config API.

Get an Approval Request

Code samples

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

GET /{tenant}/sharing/approval-requests/{approvalRequestId} HTTP/1.1

Accept: application/json


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

fetch('/{tenant}/sharing/approval-requests/{approvalRequestId}',
{
  method: 'GET',

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

GET /{tenant}/sharing/approval-requests/{approvalRequestId}

Returns the Approval Request specified by {approvalRequestId}.

Parameters

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

Example responses

200 Response

{
  "id": "123",
  "type": "approvalrequest",
  "relationshipType": "is_member_of",
  "approvalRequestType": "relationship",
  "from": {
    "id": "user1",
    "type": "user"
  },
  "to": {
    "id": "user2",
    "type": "user"
  },
  "initiates": {
    "id": "user3",
    "type": "user"
  }
}

Responses

Status Meaning Description Schema
200 OK none Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» id string true none The identifier for the Approval Request.
» type string true none The type of object, an Approval Request.
» relationshipType string true none The type of relationship to be created once the approval request is approved.
» approvalRequestType string true none The type of approval request.
» from object false none The target associated with the approval request's relationship origin
»» id string false none none
»» type string false none none
» to object false none The target associated with the approval request's relationship target
»» id string false none none
»» type string false none none
» approves object false none The Actor that approves the Approval Request.
»» id string false none none
»» type string false none none
» denies object false none The Actor that denies the Approval Request.
»» id string false none none
»» type string false none none
» initiates object false none The Actor that initiated the Approval Request
»» id string false none none
»» type string false none none

Authorization request template

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

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case approvalrequest:read) by using the Authorization Config API.

Approve an Approval Request

Code samples

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

POST /{tenant}/sharing/approval-requests/approve HTTP/1.1

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

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

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

POST /{tenant}/sharing/approval-requests/approve

Accepts an Approval Request and creates the specified Relationship between the (from) target and the (to) target.

Body parameter

{
  "approvalRequestId": "string"
}

Parameters

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

Example responses

200 Response

{
  "id": "123",
  "type": "approvalrequest",
  "relationshipType": "is_member_of",
  "approvalRequestType": "relationship",
  "from": {
    "id": "user1",
    "type": "user"
  },
  "to": {
    "id": "user2",
    "type": "user"
  },
  "initiates": {
    "id": "user3",
    "type": "user"
  }
}

Responses

Status Meaning Description Schema
200 OK none Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» id string true none The identifier for the Approval Request.
» type string true none The type of object, an Approval Request.
» relationshipType string true none The type of relationship to be created once the approval request is approved.
» approvalRequestType string true none The type of approval request.
» from object false none The target associated with the approval request's relationship origin
»» id string false none none
»» type string false none none
» to object false none The target associated with the approval request's relationship target
»» id string false none none
»» type string false none none
» approves object false none The Actor that approves the Approval Request.
»» id string false none none
»» type string false none none
» denies object false none The Actor that denies the Approval Request.
»» id string false none none
»» type string false none none
» initiates object false none The Actor that initiated the Approval Request
»» id string false none none
»» type string false none none

Authorization request template

{
  "action": "<approvalTarget>:approvalrequest:approve",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${body.approvalRequestId}",
    "type": "approvalrequest"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case <approvalTarget>:approvalrequest:approve) by using the Authorization Config API.

Deny an Approval Request

Code samples

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

POST /{tenant}/sharing/approval-requests/deny HTTP/1.1

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

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

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

POST /{tenant}/sharing/approval-requests/deny

Denies an Approval Request.

Body parameter

{
  "approvalRequestId": "string"
}

Parameters

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

Example responses

200 Response

{
  "id": "123",
  "type": "approvalrequest",
  "relationshipType": "is_member_of",
  "approvalRequestType": "relationship",
  "from": {
    "id": "user1",
    "type": "user"
  },
  "to": {
    "id": "user2",
    "type": "user"
  },
  "initiates": {
    "id": "user3",
    "type": "user"
  }
}

Responses

Status Meaning Description Schema
200 OK none Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» id string true none The identifier for the Approval Request.
» type string true none The type of object, an Approval Request.
» relationshipType string true none The type of relationship to be created once the approval request is approved.
» approvalRequestType string true none The type of approval request.
» from object false none The target associated with the approval request's relationship origin
»» id string false none none
»» type string false none none
» to object false none The target associated with the approval request's relationship target
»» id string false none none
»» type string false none none
» approves object false none The Actor that approves the Approval Request.
»» id string false none none
»» type string false none none
» denies object false none The Actor that denies the Approval Request.
»» id string false none none
»» type string false none none
» initiates object false none The Actor that initiated the Approval Request
»» id string false none none
»» type string false none none

Authorization request template

{
  "action": "<approvalTarget>:approvalrequest:deny",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${body.approvalRequestId}",
    "type": "approvalrequest"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case <approvalTarget>:approvalrequest:deny) by using the Authorization Config API.

> Resource Endpoints

List all Resources of type

Code samples

# You can also use wget
curl -X GET /{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.

Authorization request template

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

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.resourceType}:list) by using the Authorization Config API.

Create a Resource

Code samples

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

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

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

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

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

POST /{tenant}/resources/{resourceType}

Creates a Resource of type {resourceType}. The system will assign a resourceId.

Body parameter

{
  "customAttribute1": "value1",
  "customAttribute2": "value2"
}

Parameters

Name In Type Required Description
resourceType path string true The type of Resource.
tenant path string true Your tenant code.
body body object true An object specifying custom attributes for the Resource. This object must follow the JSON schema defined for the chosen ResourceType.

Example responses

201 Response

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

Responses

Status Meaning Description Schema
201 Created none Inline

Response Schema

Status Code 201

Name Type Required Restrictions Description
» id string true none The identifier of the Resource.
» type string true none The type of the Resource.
» customAttribute any false none A property defined by the tenant for this type of object.

Authorization request template

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

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.resourceType}:create) by using the Authorization Config API.

Get a Resource

Code samples

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

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

Accept: application/json


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

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

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

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

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

Parameters

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

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK none Inline
404 Not Found Returns 404 if the Resource is not found None

Response Schema

Status Code 200

Name Type Required Restrictions Description
» id string true none The identifier of the Resource.
» type string true none The type of the Resource.
» customAttribute any false none A property defined by the tenant for this type of object.

Authorization request template

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

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.resourceType}:read) by using the Authorization Config API.

Create/update a Resource

Code samples

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

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

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

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

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

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

Creates or updates the Resource specified by {resourceType} and {resourceId}.

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

Note 2: If the Resource does not exist yet, the {resourceType}:create Policy that will be evaluated. Otherwise the {resourceType}:update Policy will be evaluated

Body parameter

{
  "customAttribute1": "value1",
  "customAttribute2": "value2"
}

Parameters

Name In Type Required Description
resourceType path string true The type of Resource.
resourceId path string true The identifier for the Resource.
tenant path string true Your tenant code.
body body object true An object specifying custom attributes for the Resource. This object must follow the JSON schema defined for the chosen ResourceType.

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK none Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» id string true none The identifier of the Resource.
» type string true none The type of the Resource.
» customAttribute any false none A property defined by the tenant for this type of object.

Authorization request template

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

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.resourceType}:<createOrUpdate>) by using the Authorization Config API.

Delete a Resource

Code samples

# You can also use wget
curl -X DELETE /{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

Authorization request template

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

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.resourceType}:delete) by using the Authorization Config API.

List all Relationships

Code samples

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

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

Accept: application/json


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

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

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

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

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

Parameters

Name In Type Required Description
resourceType path string true The type of Resource.
resourceId path string true The identifier for the Resource.
signed query boolean false Optional signing of Relationships. If true, the response will contain signed Relationships. The default value is false; the response contains human-readable objects.
all query boolean false Optional inclusion of reserved RelationshipTypes. If true, the response will include the RelationshipTypes predefined by Scaled Access. The default value is false.
direction query string false Optional direction (from or to) of the Relationship with respect to the Resource specified by {resourceType} and {resourceId}.
relationship-types query string false Optional comma-separated list of RelationshipTypes to filter on.
tenant path string true Your tenant code.

Enumerated Values

Parameter Value
direction from
direction to

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK none Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
anonymous [RelationshipDetailResponse] false none none
» id string true none The identifier for the Relationship.
» relationshipType string true none The type of Relationship between the from and to Actor(s)/Resource(s).
» from NodeDetailResponse true none none
»» id string true none The identifier of the Actor/Resource.
»» type string true none The actorType or resourceType of the Actor/Resource.
» to NodeDetailResponse true none none
» properties object false none The custom properties of the Relationship.

Authorization request template

{
  "action": "${params.resourceType}:relationships:list",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "id": "${params.resourceId}",
    "type": "${params.resourceType}",
    "relationshipTypes": "${query[\"relationship-types\"]}",
    "direction": "${query[\"direction\"]}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.resourceType}:relationships:list) by using the Authorization Config API.

Create a Relationship

Code samples

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

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

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

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

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

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

Creates a Relationship for the Resource specified by {resourceType} and {resourceId}. The target must be specified with either the from or to body parameter.

Body parameter

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

Parameters

Name In Type Required Description
resourceType path string true The type of Resource.
resourceId path string true The identifier for the Resource.
tenant path string true Your tenant code.
body body object true none
» relationshipType body string true The type of relationship.
» to body object true The target Actor/Resource in the Relationship.
» properties body object false The custom properties as defined in the relationship type.

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK none RelationshipDetailResponse

Authorization request template

{
  "action": "${params.resourceType}:${body.relationshipType}:${body.to.type}:create",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${params.resourceId}",
      "type": "${params.resourceType}"
    },
    "to": {
      "id": "${body.to.id}",
      "type": "${body.to.type}"
    },
    "relationshipType": "${body.relationshipType}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.resourceType}:${body.relationshipType}:${body.to.type}:create) by using the Authorization Config API.

Delete a Relationship

Code samples

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

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

Accept: application/json


const headers = {
  'Accept':'application/json',
  '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.

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

Authorization request template

{
  "action": "${params.resourceType}:<relationshipType>:<targetType>:delete",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${params.resourceId}",
      "type": "${params.resourceType}"
    },
    "to": {
      "id": "<targetId>",
      "type": "<targetType>"
    },
    "relationshipType": "<relationshipType>",
    "relationshipId": "${params.relationshipId}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.resourceType}:<relationshipType>:<targetType>:delete) by using the Authorization Config API.

Get a Relationship

Code samples

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

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


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

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

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

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

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

Parameters

Name In Type Required Description
resourceId path string true The identifier for the Resource.
resourceType path string true The type of Resource.
relationshipId path string true The identifier for the Relationship.
tenant path string true Your tenant code.

Responses

Status Meaning Description Schema
200 OK none None

Authorization request template

{
  "action": "${params.resourceType}:<relationshipType>:<targetType>:read",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${params.resourceId}",
      "type": "${params.resourceType}"
    },
    "to": {
      "id": "<targetId>",
      "type": "<targetType>"
    },
    "relationshipType": "<relationshipType>",
    "relationshipId": "${params.relationshipId}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.resourceType}:<relationshipType>:<targetType>:read) by using the Authorization Config API.

Update a Relationship

Code samples

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

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

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

const inputBody = '{
  "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

{
  "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
» properties body object true The custom properties as defined in the relationship type.

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK none RelationshipDetailResponse

Authorization request template

{
  "action": "${params.resourceType}:<relationshipType>:<targetType>:update",
  "subject": {
    "id": "${principal.nodeId}",
    "type": "${principal.nodeType}",
    "claims": "<jwt payload>"
  },
  "resource": {
    "from": {
      "id": "${params.resourceId}",
      "type": "${params.resourceType}"
    },
    "to": {
      "id": "<targetId>",
      "type": "<targetType>"
    },
    "relationshipType": "<relationshipType>",
    "relationshipId": "${params.relationshipId}"
  }
}

Authorization Request

On the right you can find the templated authorization request that will be sent to the policy engine to determine whether the subject (based on the bearer token), is allowed to perform the action on this resource. To configure the authorization logic, change the relevant policy (in this case ${params.resourceType}:<relationshipType>:<targetType>:update) by using the Authorization Config API.

Schemas

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

NodeRequest

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

CreateApprovalRequestRequest

{
  "approvalRequestType": "relationship",
  "relationshipType": "string",
  "from": {
    "id": "string",
    "type": "string"
  },
  "to": {
    "id": "string",
    "type": "string"
  }
}

Name Type Required Restrictions Description
approvalRequestType string true none The type of approval request.
relationshipType string true none The type of relationship to be created once the approval request is approved.
from any true none none

allOf

Name Type Required Restrictions Description
» anonymous NodeRequest false none none

and

Name Type Required Restrictions Description
» anonymous any false none The target Actor/Resource in the Relationship.

continued

Name Type Required Restrictions Description
to any true none none

allOf

Name Type Required Restrictions Description
» anonymous NodeRequest false none none

and

Name Type Required Restrictions Description
» anonymous any false none The target Actor/Resource in the Relationship.
Enumerated Values
Property Value
approvalRequestType relationship

CreateApprovalRequestResponse

{
  "approvalRequestId": "string"
}

Name Type Required Restrictions Description
approvalRequestId string true read-only none

ApproveApprovalRequestRequest

{
  "approvalRequestId": "string"
}

Name Type Required Restrictions Description
approvalRequestId string true none The id of the approval request you are approving

DenyApprovalRequestRequest

{
  "approvalRequestId": "string"
}

Name Type Required Restrictions Description
approvalRequestId string true none The id of the approval request you are denying

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-telegraaf \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST /{tenant}/relationship-invitation-telegraaf 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-telegraaf',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /{tenant}/relationship-invitation-telegraaf

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

Create a OktaSync subscription

Code samples

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

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

Content-Type: application/json

const inputBody = '{
  "connect": {
    "oktaUri": "string",
    "clientId": "string",
    "privateKey": {}
  },
  "groupConfig": [
    {
      "nodeType": "string",
      "relationshipType": "string",
      "propertyMapping": {}
    }
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Authorization':'Bearer {access-token}'
};

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

POST /tenants/{tenant}/eventstream/oktasync

Create a OktaSync subscription

Body parameter

{
  "connect": {
    "oktaUri": "string",
    "clientId": "string",
    "privateKey": {}
  },
  "groupConfig": [
    {
      "nodeType": "string",
      "relationshipType": "string",
      "propertyMapping": {}
    }
  ]
}

Parameters

Name In Type Required Description
tenant path string true Your tenant code.
body body AddEventStreamOktaSyncRequest true Details for creating an OktaSync subscription.

Responses

Status Meaning Description Schema
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. None

Remove the oktasync subscription

Code samples

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

DELETE /tenants/{tenant}/eventstream/oktasync HTTP/1.1


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

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

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

DELETE /tenants/{tenant}/eventstream/oktasync

Deletes a specific subscription to the event stream.

Parameters

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

Responses

Status Meaning Description Schema
200 OK The oktasync 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

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

OktaConnectConfigRequest

{
  "oktaUri": "string",
  "clientId": "string",
  "privateKey": {}
}

Name Type Required Restrictions Description
oktaUri string true none The organisation URL of the Okta tenant. Must include 'https://' scheme
clientId string true none The Okta ClientId to use. Make sure this client has the okta.groups.manage scope enabled.
privateKey object true none The JWK provided by Okta to authenticate with the Okta API

GroupConfigRequest

{
  "nodeType": "string",
  "relationshipType": "string",
  "propertyMapping": {}
}

Name Type Required Restrictions Description
nodeType string true none The node type in the SA domain model that represents user-groups in Okta
relationshipType string true none The relationship type in the SA domain model that represents being a member of the okta user-group
propertyMapping object true none Map properties from the okta user-group to the SA node. ex: 'name': 'displayName'

AddEventStreamOktaSyncRequest

{
  "connect": {
    "oktaUri": "string",
    "clientId": "string",
    "privateKey": {}
  },
  "groupConfig": [
    {
      "nodeType": "string",
      "relationshipType": "string",
      "propertyMapping": {}
    }
  ]
}

Name Type Required Restrictions Description
connect OktaConnectConfigRequest true none Connect configuration for authorization with the Okta API
groupConfig [GroupConfigRequest] true none The mapping configuration representing the user-group memberships in Okta. Create a mapping configuration for each unique combination of nodeType and relationshipType

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