Permission object representation

The permission object representation and fields are described below.

permission was introduced in API version V1

permission has not been marked for deprecation

Usages

Permission

Description

Representation of a permission grant. Permissions are fail closed so if an object requires a permission it must be present for the subject with the given label.
Permissions represent directed edges granting a subject(type) [label] to object(type). When applied to an object the permissions will be checked for an exists style relationship from the subject scope.

Example create representation

{
  "owner" : {
    "urn" : "32a90f18-aaa0-4bdc-a63e-4efd2e16c28c",
    "url" : "/n/v1/company/32a90f18-aaa0-4bdc-a63e-4efd2e16c28c"
  },
  "subjectUrn" : "3d059a42-2095-4d19-aea9-3243787e1ccd",
  "subjectScope" : "API_CLIENT",
  "objectUrn" : "32a90f18-aaa0-4bdc-a63e-4efd2e16c28c",
  "objectScope" : "COMPANY",
  "label" : "ADMINISTER",
  "fromTimestamp" : "2025-09-05T18:36:00"
}

Example response representation

{
  "urn" : "db5d0ba1-5e7b-4c3c-ab08-5098ba68e948",
  "owner" : {
    "urn" : "32a90f18-aaa0-4bdc-a63e-4efd2e16c28c",
    "url" : "/n/v1/company/32a90f18-aaa0-4bdc-a63e-4efd2e16c28c"
  },
  "subjectUrn" : "3d059a42-2095-4d19-aea9-3243787e1ccd",
  "subjectScope" : "API_CLIENT",
  "objectUrn" : "32a90f18-aaa0-4bdc-a63e-4efd2e16c28c",
  "objectScope" : "COMPANY",
  "label" : "ADMINISTER",
  "fromTimestamp" : "2025-09-05T18:36:00"
}

Fields

Name	Type	Description	Constraints
urn	String representation of a Unique Resource Name. Typically a UUID with 36 characters.	The URN of this permission grant
owner	company	The company owning this permission	Required on create.
subjectUrn	String representation of a Unique Resource Name. Typically a UUID with 36 characters.	The subject of the permission (source) edge that receives the permission label	Required on create.
subjectScope	String literal	Type of the subject scope URN	Allowed values: ANY ACCOUNT API_CLIENT COMPANY EMAIL_ADDRESS ENTITY IDENTITY ORGANISATION PAYMENT_CARD PERSON ROLE TELEPHONE USER GROUP OAUTH_TOKEN UNRECOGNIZED
objectUrn	String representation of a Unique Resource Name. Typically a UUID with 36 characters.	The object URN for the permission to be granted on	Required on create.
objectScope	String literal	Type of the object scope URN	Allowed values: ANY ACCOUNT API_CLIENT COMPANY EMAIL_ADDRESS ENTITY IDENTITY ORGANISATION PAYMENT_CARD PERSON ROLE TELEPHONE USER GROUP OAUTH_TOKEN UNRECOGNIZED
label	String literal	The permission label to grant. We typically use a set of values for our use cases but any value can be used.	Minimum length: 1. Maximum length: 255. Allowed values: ALL CREATE READ UPDATE DELETE ADMINISTER MODERATE ARCHIVE UNRECOGNIZED
fromTimestamp	Timestamp expressed in ISO 8601 format without timezone including milliseconds. Note unless otherwise stated in UTC zone.	The timestamp from which this permission is active
toTimestamp	Timestamp expressed in ISO 8601 format without timezone including milliseconds. Note unless otherwise stated in UTC zone.	The timestamp to which the permission is granted. N.B. the default unix timestamp of 0 epoch millis is equivalent to not set