Access Profiles and Grants API

Overview

These APIs let you manage (create/read/update/delete) roles for a principal in your organization. A principal and its access to the system is governed by the grant assigned. A principal can only have 1 grant. That grant can contain a role OR multiple profiles of role assignments.

Requirements

  • At least one Carbon Black Cloud product with identity managed within Carbon Black Cloud.
  • All API calls require an API key with appropriate permissions see Authentication

Note: If your organization uses VMware Cloud Services with Carbon Black Cloud, users and their permissions are managed in the VMware Cloud Services console and these APIs are not available. Further information is available in the VMware Carbon Black Cloud on VMware Cloud Services Platform. This includes all organizations using the UK point of presence (Prod UK) and AWS GovCloud (US).

Guides and Resources

Authentication

Access Level and API Key:

When creating your API Key, this API requires a different process for creating the appropriate Access Level than is outlined in the Carbon Black Cloud Authentication Guide.

The API Key used to create users must have all the permissions being granted to the new users and “Manage Roles” and “Manage Users” from the “Organization Settings”.

Option 1

  • Navigate to Settings > API Access in the Carbon Black Cloud console, and add a new API Key with a “Custom” Access Level and choose “Super Admin” from the Custom Access Level dropdown. This will grant the maximum permissions to the API Key and allow the key to grant any role.

Option 2

It is recommended to limit access to only the necessary permissions, so the “Super Admin” Access Level may not be right for you. To create a new Access Level with more limited permissions:

  • Navigate to Settings > Roles in the console.
  • Add a new Role and then use the category expanders to add permissions to the role. At minimum, you must add the permissions for
    • “Manage Roles” and “Manage Users” from the “Organization Settings” category; and
    • All permissions to be granted to users
    • Some examples:
      • If you want the script to be able to create users with only View All role, the user-creating role needs all the permissions in View All and “Manage Roles” and “Manage Users”.
      • If you want the script to be able to create users with View All, Level 1 Analyst or Level 2 Analyst role, the user-creating role needs all the permissions in each of those three roles and “Manage Roles” and “Manage Users”.
    • This is to prevent privilege escalation and is the same restriction as the UI enforces: no user is able to create user accounts that have more permission than they already have. If a user could create a new user with additional permissions, they could then login with the new account, and have then increased their privileges with no authorisation.
  • It may be helpful to copy permissions from the standard role to be given to new users and add the “Manage Roles” and “Manage Users” permissions on top of the base permissions for that role.
  • Once you configure the role to your liking, hit save, and then add a new API Key from Settings > API Access, select “Custom” Access Level, and choose the new role from the Custom Access Level dropdown.
Note: You can only create Roles with the same level of permissions granted to you. You may need a Super Admin to assist in creating the new Role and API Key. The Super Admin assignment must be a role.

Environment Details:

Quick Start

Assign multiple roles to an existing user

This guide explains how to change the access profile for an existing user in a multi-tenant environment.

  1. Get the existing Grant for a user with the Get Grant of a Principal call.
  2. Get the list of roles the API Key or User specified in the request can manage in the organization or its children organizations with the Get Permitted Roles call.
  3. Update the existing Profile for that user to add another organization using the Update Profile of Principal’s Grant call.
  4. Update the Grant to add a new profile with different permissions in another organization with the Create Profile in Principal’s Grant call.

Basic user creation with a grant

  1. Create a new user with Level 1 Analyst role with the User Management API - Create User call.
  2. User receives an invite in mail and follows instructions for registration.
  3. Check if the new user is included in the Organization with the User Management API - List All Users call.
  4. View the details of the User Grant with the Get Grant of a Principal call.

API Calls

Create Grant for a Principal

Create grant for a Principal in given Org.

Note: When using a role grant, you can only select one role. The profiles however do support multiple roles.
Role Permissions
Manage Users

Request

POST {cbc-hostname}/access/v2/orgs/{org_key}/grants/

Request Body - application/json

{
  "principal": "string",
  "roles": [ "string" ],
  "profiles": [
    {
      "orgs": {
        "allow": [ "string" ],
      },
      "roles": [ "string" ],
      "conditions": {
        "expiration": "string",
        "disabled": boolean
      }
    }
  ],
  "org_ref": "string",
  "principal_name": "string"
}

Body Schema

Field Definition Data Type Values
principal
REQUIRED 		Uniform Resource Name String Format:
psc:user:{org_key}:{login_id}
or
psc:cnn:{org_key}:{connector_id}
roles
REQUIRED 		Role attached to grant. Accepts only one value. Either roles or profiles can be used, but not both.

Recommendation: Use roles if you plan to add access to a single organization		 Array 
[ "string" ]
Format:
psc:role:{org_key}:{role_name}
profiles
REQUIRED 		List of profiles attached to grant. Either roles or profiles can be used, but not both.

Recommendation: Use profiles if you plan to add access to two or more child orgs		 Array Profile Schema
org_ref
REQUIRED 		Org reference in urn format String Format:
psc:org:{org_key}
principal_name
REQUIRED 		Principals name String N/A
conditions Conditions attached to a profile Object Condition Schema

Response

Code Description Content-Type Content
201 Successful Request application/json View example response below
400 Bad request application/json 
{
  "error_code": "BAD_REQUEST",
  "message": "Principal resource must match request body"
}
401 Unauthorized application/json 
{
  "success": false,
  "message": "User is not authenticated"
}
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Examples

Request 
POST https://defense.conferdeploy.net/access/v2/orgs/ABCD1234/grants
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "principal": "psc:user:ABCD1234:1234567",
  "profiles": [
    {
      "orgs": {
        "allow": [ "psc:org:ABCD1234" ],
      },
      "roles": [ "psc:role::SECOPS_ROLE_MANAGER" ]
    }
  ],
  "org_ref": "psc:org:ABCD1234",
  "principal_name": "demo@vmware.com"
}
Response Body 
{
  "principal": "psc:user:ABCD1234:1234567",
  "roles": null,
  "profiles": [
    {
      "orgs": {
        "allow": [ "psc:org:ABCD1234" ],
      },
      "roles": [ "psc:role::SECOPS_ROLE_MANAGER" ],
      "conditions": {
        "expiration": "",
        "disabled": true
      },
      "can_manage": true
    }
  ],
  "org_ref": "psc:org:ABCD1234",
  "principal_name": "demo@vmware.com",
  "created_by": "psc:user:ABCD1234:DEFG1234",
  "updated_by": "psc:user:ABCD1234:DEFG1234",
  "create_time": "2021-01-19T12:56:31.645Z",
  "update_time": "2021-01-19T12:56:31.645Z",
  "can_manage": true
}
To download or review the Carbon Black Cloud Postman collection, click here.
Request 
POST https://defense.conferdeploy.net/access/v2/orgs/ABCD1234/grants
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
  "principal": "psc:user:ABCD1234:1234567",
  "roles": [ "psc:role::SECOPS_ROLE_MANAGER" ],
  "org_ref": "psc:org:ABCD1234",
  "principal_name": "demo@vmware.com"
}
Response Body 
{
  "principal": "psc:user:ABCD1234:1234567",
  "roles": [ "psc:role::SECOPS_ROLE_MANAGER" ],
  "profiles": null,
  "org_ref": "psc:org:ABCD1234",
  "principal_name": "demo@vmware.com",
  "created_by": "psc:user:ABCD1234:DEFG1234",
  "updated_by": "psc:user:ABCD1234:DEFG1234",
  "create_time": "2021-01-19T12:56:31.645Z",
  "update_time": "2021-01-19T12:56:31.645Z",
  "can_manage": true
}
To download or review the Carbon Black Cloud Postman collection, click here.

Get Grant of a Principal

Get grant of a Principal(User or API Key) in a given Organization.

Role Permissions
Manage Roles

Request

GET {cbc-hostname}/access/v2/orgs/{org_key}/grants/{principal_urn}

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
401 Unauthorized application/json 
{
  "success": false,
  "message": "User is not authenticated"
}
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/access/v2/orgs/ABCD1234/grants/psc:user:ABCD1234:DEFG1234

Response 

{
    "principal": "psc:user:ABCD1234:1234567",
    "roles": [ "psc:role::CUSTOM_ROLE" ],
    "version": 1,
    "profiles": null,
    "org_ref": "psc:org:ABCD1234",
    "principal_name": "demo@vmware.com",
    "created_by": "psc:cnn:ABCD1234:DEFG1234",
    "updated_by": "psc:cnn:ABCD1234:DEFG1234",
    "create_time": "2021-04-05T06:56:23.348Z",
    "update_time": "2021-04-05T06:56:23.348Z",
    "can_manage": true
}

Bulk Fetch Grants

Bulk fetch grants for list of Principals and Organizations key pair.

Role Permissions
Manage Roles

Request

POST {cbc-hostname}/access/v2/grants/_fetch

Request Body - application/json

[
  {
    "principal": "string",
    "org_ref": "string"
  }
]

Body Schema

Field Definition Data Type Values
principal
REQUIRED 		Uniform Resource Name String Format:
psc:user:{org_key}:{login_id}
or
psc:cnn:{org_key}:{connector_id}
org_ref
REQUIRED 		Org reference in urn format String Format:
psc:org:{org_key}

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
401 Unauthorized application/json 
{
  "success": false,
  "message": "User is not authenticated"
}
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense-eap01.conferdeploy.net/access/v2/grants/_fetch

Request_Body 

[
  {
    "principal": "psc:user:ABCD1234:1234567",
    "org_ref": "psc:org:ABCD1234"
  },
    {
    "principal": "psc:user:ABCD1234:7654321",
    "org_ref": "psc:org:ABCD1234"
  }
]

Response 

{
    "results": [
        {
            "principal": "psc:user:ABCD1234:1234567",
            "roles": null,
            "version": 3,
            "profiles": [
                {
                    "profile_uuid": "01a27d93-1974-492a-9e95-d92d66b2d123",
                    "orgs": {
                        "allow": [ "psc:org:ABCD1234" ]
                    },
                    "roles": [ "psc:role:ABCD1234:MANAGE_ANALYST_1_ROLE" ],
                    "conditions": null,
                    "can_manage": true
                }
            ],
            "org_ref": "psc:org:ABCD1234",
            "principal_name": demo@vmware.com,
            "created_by": "psc:cnn:ABCD1234:DEFG1234",
            "updated_by": "psc:cnn:ABCD1234:DEFG1234",
            "create_time": null,
            "update_time": null,
            "can_manage": true
        },
        {
            "principal": "psc:user:ABCD1234:7654321",
            "roles": [ "psc:role:ABCD1234:LEVEL_1_ANALYST_WITH_MANAGE_USERS" ],
            "version": 1,
            "profiles": null,
            "org_ref": "psc:org:ABCD1234",
            "principal_name": "demo@vmware.com",
            "created_by": "psc:cnn:ABCD1234:DEFG1234",
            "updated_by": "psc:cnn:ABCD1234:DEFG1234",
            "create_time": null,
            "update_time": null,
            "can_manage": true
        }
    ]
}

Update Grant of a Principal

Update grant of a Principal in given Organization.

Note: The entire grant will be updated including the profiles. Be aware that this will generate new profile_uuids for each profile.
Role Permissions
Manage Roles, Manage Users

Request

PUT {cbc-hostname}/access/v2/orgs/{org_key}/grants/{principal_urn}

Request Body

{
    "principal": "<string>",
    "roles": [ "<string>" ],
    "profiles": [
        {
            "profile_uuid": "<string>",
            "orgs": {
                "allow": [ "<string>" ]
            },
            "roles": [ "<string>" ],
            "conditions": {
              "expiration": "string",
              "disabled": boolean
            }
        }
    ],
    "org_ref": "<string>",
    "principal_name": "<string>"
}

Body Schema

Field Definition Data Type Values
principal
REQUIRED 		Uniform Resource Name String Format:
psc:user:{org_key}:{login_id}
or
psc:cnn:{org_key}:{connector_id}
roles Role attached to grant. Accepts only one value. Either roles or profiles can be used, but not both.

Recommendation: Use roles if you plan to add access to a single organization		 Array 
[ "string" ]
Format:
psc:role:{org_key}:{role_name}
profiles List of profiles attached to grant. Either roles or profiles can be used, but not both.

Recommendation: Use profiles if you plan to add access to two or more child orgs		 Array Profile Schema
org_ref
REQUIRED 		Org reference in urn format String Format:
psc:org:{org_key}
principal_name
REQUIRED 		Principals name String N/A

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
400 Bad request application/json 
{
  "error_code": "BAD_REQUEST",
  "message": "Roles must be set"
}
401 Unauthorized application/json 
{
  "success": false,
  "message": "User is not authenticated"
}
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

PUT https://defense-eap01.conferdeploy.net/access/v2/orgs/ABCD1234/grants/psc:user:ABCD1234:DEFG1234

Request_Body 

{
  "principal": "psc:user:ABCD1234:1234567",
  "roles": [ "psc:role:ABCD1234:CUSTOM_ROLE" ],
  "org_ref": "psc:org:ABCD1234",
  "principal_name": "demo@vmware.com"
}

Response 

{
  "principal": "psc:user:ABCD1234:1234567",
  "roles": [ "psc:role:ABCD1234:CUSTOM_ROLE" ],
  "org_ref": "psc:org:ABCD1234",
  "principal_name": "demo@vmware.com",
  "created_by": "psc:user:ABCD1234:DEFG1234",
  "updated_by": "psc:user:ABCD1234:DEFG1234",
  "create_time": "2021-01-19T12:56:31.645Z",
  "update_time": "2021-01-19T12:56:31.645Z",
  "can_manage": true
}

Delete Grant for a Principal

Delete grant for a Principal in given Organization.

Role Permissions
Manage Roles

Request

DELETE {cbc-hostname}/access/v2/orgs/{org_key}/grants/{principal_urn}

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
401 Unauthorized application/json 
{
  "success": false,
  "message": "User is not authenticated"
}
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

DELETE https://defense-eap01.conferdeploy.net/access/v2/orgs/ABCD1234/grants/psc:user:ABCD1234:DEFG1234

Response 

{
  "principal": "psc:user:ABCD1234:1234567",
  "roles": [ "psc:role:ABCD1234:CUSTOM_ROLE" ],
  "org_ref": "psc:org:ABCD1234",
  "principal_name": "demo@vmware.com",
  "created_by": "psc:user:ABCD1234:DEFG1234",
  "updated_by": "psc:user:ABCD1234:DEFG1234",
  "create_time": "2021-01-19T12:56:31.645Z",
  "update_time": "2021-01-19T12:56:31.645Z",
  "can_manage": true
}

Get Permitted Roles

Returns a list of roles that may be managed by the user making the request. Helps to identify roles in an organization and its child organizations (in a multi-tenant environment).

Note: In order for this API call to function correctly, the {token} in the endpoint URL below **must** match the 'token' portion of the API credentials specified in the 'X-Auth-Token' header (everything after the '/' character). Otherwise, a '403 Forbidden' error will be returned.
Role Permissions
Manage Roles

Request

GET {cbc-hostname}/access/v3/orgs/{org_key}/principals/{token}/roles/permitted

Query Parameters

Parameter Required Default Description
type Yes N/A Type of roles to be returned. Supported: USER, API_KEY

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
400 Bad Request N/A N/A
401 Unauthorized application/json 
{
  "success": false,
  "message": "User is not authenticated"
}
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

GET https://defense-eap01.conferdeploy.net/access/v3/orgs/ABCD1234/principals/A1B2C3D4/roles/permitted?type=USER

Response 

{
    "results": {
        "ABCD1234": [
            {
                "urn": "psc:role::CONTAINER_IMAGE_CLI_TOOL",
                "scoped": "psc:org:org-scope:all",
                "name": "Container Image CLI tool",
                "desc": "Upload image SBOMs, and view container image and Kubernetes data",
                "disabled": false,
                "capabilities": [
                    "api",
                    "private_api",
                    "public_api"
                ],
                "child_urn": "psc:role::CONTAINER_IMAGE_CLI_TOOL",
                "created_by": "psc:cnn:ABCD1234:9Z8Y7X6W5V",
                "updated_by": "psc:cnn:ABCD1234:9Z8Y7X6W5V",
                "create_time": "2021-04-13T17:51:34.539Z",
                "update_time": "2021-04-13T17:51:34.539Z"
            },
            {
                "urn": "psc:role::BETA_SUPER_ADMIN",
                "scoped": "psc:org:org-scope:all",
                "name": "Super Admin",
                "desc": "All permissions, including console configuration, Live Response, and management of policies, API keys, and sensor group rules",
                "disabled": false,
                "capabilities": [
                    "user"
                ],
                "child_urn": "psc:role::BETA_SUPER_ADMIN",
                "created_by": null,
                "updated_by": "psc:cnn:ABCD1234:9Z8Y7X6W5V",
                "create_time": "",
                "update_time": "2021-05-05T06:03:09.998Z"
            },
            {
                "urn": "psc:role::VIEW_ONLY",
                "scoped": "psc:org:org-scope:all",
                "name": "View Only - Legacy",
                "desc": "View Only",
                "disabled": false,
                "capabilities": [
                    "user"
                ],
                "child_urn": "psc:role::VIEW_ONLY",
                "created_by": null,
                "updated_by": "psc:cnn:ABCD1234:9Z8Y7X6W5V",
                "create_time": "",
                "update_time": "2021-03-16T01:02:54.214Z"
            }
        ],
        "ABCD1234:CHILDREN": [
            {
                "urn": "psc:role::KUBERNETES_SECURITY_DEVOPS",
                "scoped": "psc:org:org-scope:all",
                "name": "Kubernetes Security DevOps",
                "desc": "Manage Kubernetes security features",
                "disabled": false,
                "capabilities": [
                    "user"
                ],
                "child_urn": "psc:role::KUBERNETES_SECURITY_DEVOPS",
                "created_by": null,
                "updated_by": "psc:cnn:ABCD1234:9Z8Y7X6W5V",
                "create_time": "",
                "update_time": "2020-11-20T20:43:15.961Z"
            },
            {
                "urn": "psc:role::BETA_SYSTEM_ADMIN",
                "scoped": "psc:org:org-scope:all",
                "name": "System Admin",
                "desc": "Manage sensors, add users, and enable bypass; can't change global settings, delete files, or use Live Response",
                "disabled": false,
                "capabilities": [
                    "user"
                ],
                "child_urn": "psc:role::BETA_SYSTEM_ADMIN",
                "created_by": null,
                "updated_by": "psc:cnn:ABCD1234:9Z8Y7X6W5V",
                "create_time": "",
                "update_time": "2021-05-05T06:03:09.084Z"
            }
        ]
    }
}

Create Profile in Principal’s Grant

Create profile in Principal’s grant in given Organization.

Role Permissions
Manage Roles

Request

POST {cbc-hostname}/access/v2/orgs/{org_key}/grants/{principal_urn}/profiles

Request Body - application/json

{
    "orgs": {
        "allow": [ "<string>" ],
    },
    "roles": [ "<string>" ],
    "conditions": {
      "expiration": "string",
      "disabled": boolean
    }
}

Body Schema

Field Definition Data Type Values
orgs
REQUIRED 		Allowed/denied Orgs in the current Profile Object Orgs Schema
roles
REQUIRED 		Role attached to a profile Array 
[ "string" ]
conditions Conditions attached to a profile Object Condition Schema

Response

Code Description Content-Type Content
201 Successful Request application/json View example response below
400 Bad request application/json 
{
  "error_code": "BAD_REQUEST",
  "message": "Orgs must be defined for each profile"
}
401 Unauthorized application/json 
{
  "success": false,
  "message": "User is not authenticated"
}
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

POST https://defense-eap01.conferdeploy.net/access/v2/orgs/ABCD1234/grants/psc:user:ABCD1234:DEFG1234/profiles

Request_Body 

{
  "orgs": {
    "allow": [ "psc:org:ABCD1234" ],
  },
  "roles": [ "psc:role::SECOPS_ROLE_MANAGER" ],
  "conditions": {
  }
}

Response 

{
  "orgs": {
    "allow": [ "psc:org:ABCD1234" ],
  },
  "roles": [ "psc:role::SECOPS_ROLE_MANAGER" ],
  "conditions": {
    "expiration": "string",
    "disabled": true
  },
  "can_manage": true
}

Update Profile of Principal’s Grant

Update profile of Principal’s grant in given Organization.

Role Permissions
Manage Roles

Request

PUT {cbc-hostname}/access/v2/orgs/{org_key}/grants/{principal_urn}/profiles/{profile_uuid}

Request Body

{
  "profile_uuid": "string",
  "orgs": {
    "allow": [ "string" ],
  },
  "roles": [ "string" ],  
  "conditions": {
    "expiration": "string",
    "disabled": boolean
  }
}

Body Schema

Field Definition Data Type Values
profile_uuid Universally Unique Identifier String N/A
orgs Allowed/denied Orgs in the current Profile Object Orgs Schema
roles
REQUIRED 		Role attached to a profile Array 
[ "string" ]
Example:
psc:role::SECOPS_ROLE_MANAGER
conditions Conditions attached to a profile Object Condition Schema

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
400 Bad request application/json 
{
  "error_code": "BAD_REQUEST",
  "message": "profile_uuid must not be null"
}
401 Unauthorized application/json 
{
  "success": false,
  "message": "User is not authenticated"
}
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

PUT https://defense-eap01.conferdeploy.net/access/v2/orgs/ABCD1234/grants/psc:user:ABCD1234:DEFG1234/profiles/3fa85f64-5717-4562-b3fc-2c963f66afa6

Request_Body 

{
  "profile_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "orgs": {
    "allow": [ "psc:org:ABCD1234" ],
  },
  "roles": [ "psc:role::SECOPS_ROLE_MANAGER" ],
  "conditions": {
  }
}

Response 

{
  "profile_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "orgs": {
    "allow": [ "psc:org:ABCD1234" ],
  },
  "roles": [ "psc:role::SECOPS_ROLE_MANAGER" ],
  "conditions": {
    "expiration": "2021-01-27T18:34:04Z",
    "disabled": true
  },
  "can_manage": true
}

Delete Profile

Delete profile with matching uuid from Principal’s grant in given Organization.

Role Permissions
Manage Roles

Request

DELETE {cbc-hostname}/access/v2/orgs/{org_key}/grants/{principal_urn}/profiles/{profile_uuid}

Response

Code Description Content-Type Content
200 Successful Request application/json View example response below
401 Unauthorized application/json 
{
  "success": false,
  "message": "User is not authenticated"
}
403 Forbidden N/A N/A
404 Not found N/A N/A
500 Internal Server Error N/A N/A

Example

Request

DELETE https://defense-eap01.conferdeploy.net/access/v2/orgs/ABCD1234/grants/psc:user:ABCD1234:DEFG1234/profiles/3fa85f64-5717-4562-b3fc-2c963f66afa6

Response 

{
  "profile_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "orgs": {
    "allow": [ "psc:org:ABCD1234" ],
  },
  "roles": [ "psc:role::SECOPS_ROLE_MANAGER" ],
  "conditions": {
    "expiration": "2021-01-27T18:34:04Z",
    "disabled": true
  },
  "can_manage": true
}

Fields

Condition

Field Definition Data Type Values
expiration ISO 8601 UTC extended time format indicating when the profile condition will expire String Example: 2021-04-07T17:49:58.792Z
disabled Indicating if the profile is disabled Boolean Supported: true, false

Grant

Field Definition Data Type Values
principal
REQUIRED 		Principals URN String Format:
psc:user:{org_key}:{login_id}
or
psc:cnn:{org_key}:{connector_id}
roles Role attached to a grant. Accepts only one value. Either roles or profiles can be used, but not both. Array 
[ "string" ]
Format:
psc:role:{org_key}:{role_name}
profiles List of profiles attached to a grant. Either roles or profiles can be used, but not both. Array Profile Schema
org_ref
REQUIRED 		Org reference in Urn format String Format:
psc:org:{org_key}
principal_name
REQUIRED 		Principals name String N/A
created_by Principals URN who created the grant String Format:
psc:user:{org_key}:{login_id}
or
psc:cnn:{org_key}:{connector_id}
updated_by Principals URN who last updated the grant String Format:
psc:user:{org_key}:{login_id}
or
psc:cnn:{org_key}:{connector_id}
create_time ISO 8601 UTC extended time format indicating when the grant has been created String Example: 2021-04-07T17:49:58.792Z
update_time ISO 8601 UTC extended time format indicating when last time the grant has been updated String Example: 2021-04-07T17:49:58.792Z
can_manage Indicates whether the requesting user can manage the grant and/or the individual profiles Boolean Supported: true, false
version Numerical tag incremented by backend on each update. This property is not editable. Integer N/A

Orgs

Field Definition Data Type Values
allow
REQUIRED 		List of allowed Orgs in the current Profile Array 
[ "string" ]
Format:
psc:org:{org_key}

Profile

Field Definition Data Type Values
profile_uuid UUID String N/A
orgs N/A Object Orgs Schema
roles
REQUIRED 		Role attached to a profile. Accepts only one value Array 
[ "string" ]
Example:
psc:role::SECOPS_ROLE_MANAGER
conditions Conditions attached to a profile Object Condition Schema
can_manage Indicates whether the requesting user can manage the grant and/or the individual profiles Boolean Supported: true, false

Role

Note: psc:org:{org_key}:CHILDREN is a special URN that allows you to grant access to all current and future children of a multi-tenant environment parent where {org_key} is the parent. If you create this type of profile, you must have the appropriate access to all the children.
Field Definition Data Type Values
urn
REQUIRED 		Role URN String Format: psc:role:{org_key}:{role} or psc:role::{role} or psc:org:{org_key}:CHILDREN
scoped Scoped URN String Format: psc:org:org-scope:csr-all or for org specific roles psc:org:ORGKEY
name
REQUIRED 		Role name String N/A
desc Role description String N/A
disabled Value indicating if the role is disabled Boolean Supported: true, false
capabilities
REQUIRED 		Array 
[ "string" ]
Supported: api, internal, private_api, public_api, non_grantable
child_urn
REQUIRED 		Role URN String Format: psc:role:{org_key}:{role} or psc:role::{role}
created_by Principals URN who created the grant String Format: psc:user:{org_key}:{login_id} or psc:cnn:{org_key}:{connector_id}
updated_by Principals URN who last updated the grant String Format psc:user:{org_key}:{login_id} or psc:cnn:{org_key}:{connector_id}
create_time ISO 8601 UTC timestamp when the grant has been created String Example: 2021-04-07T17:49:58.792Z
update_time ISO 8601 UTC timestamp when last time the grant has been updated String Example: 2021-04-07T17:49:58.792Z

Last modified on January 19, 2024