Access Policy

Direct grants and scoped role assignments.

Methods on this page are called through client.access_policy.

client.access_policy.check

client.access_policy.check(request: CheckAuthorizationsRequest, requestOptions?: RequestOptions): Promise<CheckAuthorizationsResponseShape>

Evaluates 1 to 50 concrete operation-and-target checks under the authenticated caller's live authority and any API-key ceiling. Results are positional and advisory: missing targets and denied operations both return allowed=false, and every later resource request performs fresh authorization. Top-level creates target INSTANCE; CREATE_MEMORY and LIST_MEMORY target their parent SPACE; reads, mutations, proxy operations, and access-policy administration target concrete resources. LIST_API_KEY and LIST_RETRIEVE_MEMORY_LOG_POLICY are rejected because their current candidate-based list rules have no instance-wide preflight.

HTTP: POST /v1/access-policy:check

Parameters

Parameter	Type	Description
`request`	`CheckAuthorizationsRequest`	Request body.
`requestOptions`	`RequestOptions` optional	Per-call signal, timeout, or headers.

Returns: Promise<CheckAuthorizationsResponseShape>

Example

const authorizationDecisions = await client.accessPolicy.check({
  checks: [
    {
      operation: "READ_INSTANCE",
      target: { kind: "INSTANCE" },
    },
  ],
});
console.log(authorizationDecisions.results[0]?.allowed);

client.access_policy.grantsCreate

client.access_policy.grantsCreate(request: CreateAuthorizationGrantRequest, requestOptions?: RequestOptions): Promise<AuthorizationGrantResponseShape>

Creates one direct grant after resolving its typed policy target and requiring MANAGE_ACCESS. Direct grants cannot confer credential-read or ownership-transfer authority. ALL_AUTHENTICATED grants require an assigned-resource selector. MANAGE_ACCESS and MANAGE_USER_ENROLLMENT require a concrete principal and ANY or EXACT; MANAGE_USER_ENROLLMENT with EXACT must target USER.

HTTP: POST /v1/access-policy/grants

Parameters

Parameter	Type	Description
`request`	`CreateAuthorizationGrantRequest`	Request body.
`requestOptions`	`RequestOptions` optional	Per-call signal, timeout, or headers.

Returns: Promise<AuthorizationGrantResponseShape>

Example

const grant = await client.accessPolicy.grantsCreate({
  audience: { principalId },
  rule: {
    operation: "READ_SPACE",
    selector: "EXACT",
    assignedResource: { kind: "SPACE", resourceId: policySpaceId },
  },
});

client.access_policy.grantsDelete

client.access_policy.grantsDelete(id: string, requestOptions?: RequestOptions): Promise<AuthorizationGrantResponseShape>

Soft-revokes one grant and returns its durable historical row. Repeating the request is idempotent while the caller retains MANAGE_ACCESS on the target.

HTTP: DELETE /v1/access-policy/grants/{id}

Parameters

Parameter	Type	Description
`id`	`string`	Grant UUID
`requestOptions`	`RequestOptions` optional	Per-call signal, timeout, or headers.

Returns: Promise<AuthorizationGrantResponseShape>

Example

const revokedGrant = await client.accessPolicy.grantsDelete(grant.grantId);

client.access_policy.grantsGet

client.access_policy.grantsGet(id: string, options?: AccessPolicyGrantsGetOptions, requestOptions?: RequestOptions): Promise<AuthorizationGrantResponseShape>

Reads one live grant, or one revoked historical grant when includeRevoked is true, after requiring MANAGE_ACCESS on its policy target.

HTTP: GET /v1/access-policy/grants/{id}

Parameters

Parameter	Type	Description
`id`	`string`	Grant UUID
`options`	`AccessPolicyGrantsGetOptions` optional	Optional query parameters.
`requestOptions`	`RequestOptions` optional	Per-call signal, timeout, or headers.

Returns: Promise<AuthorizationGrantResponseShape>

Example

const fetchedGrant = await client.accessPolicy.grantsGet(grant.grantId);

client.access_policy.grantsList

client.access_policy.grantsList(options?: AccessPolicyGrantsListOptions, requestOptions?: RequestOptions): Promise<Page<AuthorizationGrantResponseShape>>

Lists grants attached to one resource. MANAGE_ACCESS is required on that resource; continuation tokens are bound to the caller and filters.

HTTP: GET /v1/access-policy/grants

Parameters

Parameter	Type	Description
`options`	`AccessPolicyGrantsListOptions` optional	Optional query parameters.
`requestOptions`	`RequestOptions` optional	Per-call signal, timeout, or headers.

Returns: Promise<Page<AuthorizationGrantResponseShape>>

Example

for await (const visibleGrant of await client.accessPolicy.grantsList({
  resourceKind: "SPACE",
  resourceId: policySpaceId,
})) {
  console.log(visibleGrant.grantId);
}

client.access_policy.roleAssignmentsCreate

client.access_policy.roleAssignmentsCreate(request: AssignRoleRequest, requestOptions?: RequestOptions): Promise<RoleAssignmentResponseShape>

Assigns one code-defined role to an active principal at INSTANCE or SPACE scope after requiring MANAGE_ACCESS. ROOT is maintained only by ownership workflows.

HTTP: POST /v1/access-policy/role-assignments

Parameters

Parameter	Type	Description
`request`	`AssignRoleRequest`	Request body.
`requestOptions`	`RequestOptions` optional	Per-call signal, timeout, or headers.

Returns: Promise<RoleAssignmentResponseShape>

Example

const assignment = await client.accessPolicy.roleAssignmentsCreate({
  principalId,
  role: "SPACE_VIEWER",
  assignedResource: { kind: "SPACE", resourceId: policySpaceId },
});

client.access_policy.roleAssignmentsDelete

client.access_policy.roleAssignmentsDelete(id: string, requestOptions?: RequestOptions): Promise<RoleAssignmentResponseShape>

Soft-revokes one non-ROOT assignment and returns its durable historical row. Repeating the request is idempotent while the caller retains MANAGE_ACCESS.

HTTP: DELETE /v1/access-policy/role-assignments/{id}

Parameters

Parameter	Type	Description
`id`	`string`	Role-assignment UUID
`requestOptions`	`RequestOptions` optional	Per-call signal, timeout, or headers.

Returns: Promise<RoleAssignmentResponseShape>

Example

const revokedAssignment = await client.accessPolicy.roleAssignmentsDelete(
  assignment.roleAssignmentId,
);

client.access_policy.roleAssignmentsGet

client.access_policy.roleAssignmentsGet(id: string, options?: AccessPolicyRoleAssignmentsGetOptions, requestOptions?: RequestOptions): Promise<RoleAssignmentResponseShape>

Reads one live assignment, or one revoked historical assignment when includeRevoked is true, after requiring MANAGE_ACCESS on its policy target.

HTTP: GET /v1/access-policy/role-assignments/{id}

Parameters

Parameter	Type	Description
`id`	`string`	Role-assignment UUID
`options`	`AccessPolicyRoleAssignmentsGetOptions` optional	Optional query parameters.
`requestOptions`	`RequestOptions` optional	Per-call signal, timeout, or headers.

Returns: Promise<RoleAssignmentResponseShape>

Example

const fetchedAssignment = await client.accessPolicy.roleAssignmentsGet(
  assignment.roleAssignmentId,
);

client.access_policy.roleAssignmentsList

client.access_policy.roleAssignmentsList(options?: AccessPolicyRoleAssignmentsListOptions, requestOptions?: RequestOptions): Promise<Page<RoleAssignmentResponseShape>>

Lists assignments attached to one required INSTANCE or SPACE boundary after requiring MANAGE_ACCESS. Continuation tokens are bound to the caller and filters.

HTTP: GET /v1/access-policy/role-assignments

Parameters

Parameter	Type	Description
`options`	`AccessPolicyRoleAssignmentsListOptions` optional	Optional query parameters.
`requestOptions`	`RequestOptions` optional	Per-call signal, timeout, or headers.

Returns: Promise<Page<RoleAssignmentResponseShape>>

Example

for await (const visibleAssignment of await client.accessPolicy.roleAssignmentsList({
  resourceKind: "SPACE",
  resourceId: policySpaceId,
})) {
  console.log(visibleAssignment.roleAssignmentId);
}

Data Models

Enum Values

GrantAudienceAllAuthenticated

True

Role

ROOT, ADMIN, USER, SPACE_VIEWER, SPACE_CONTRIBUTOR, SPACE_CONTENT_MANAGER, SPACE_ADMIN

Interfaces

AssignRoleRequest

Assigns one code-defined role at an INSTANCE or SPACE boundary.

Field	Type	Required	Description
`roleAssignmentId`	`string \| null`	no	Optional caller-provided role-assignment UUID.
`principalId`	`string`	yes	Active principal receiving the role.
`role`	`"ADMIN" \| "USER" \| "SPACE_VIEWER" \| "SPACE_CONTRIBUTOR" \| "SPACE_CONTENT_MANAGER" \| "SPACE_ADMIN"`	yes	Code-defined non-ROOT role to assign.
`assignedResource`	`RoleAssignmentTarget`	yes	INSTANCE or SPACE boundary receiving the assignment.

AuthorizationCheck

One concrete, advisory authorization check. Top-level creates target INSTANCE; CREATE_MEMORY and LIST_MEMORY target a parent SPACE; ordinary resource operations target the concrete resource. LIST_API_KEY and LIST_RETRIEVE_MEMORY_LOG_POLICY are not supported by this endpoint.

Field	Type	Required	Description
`operation`	`Operation`	yes	Operation the caller proposes to perform.
`target`	`AccessPolicyTarget`	yes	Target required by the operation: INSTANCE for top-level creates, parent SPACE for CREATE_MEMORY or LIST_MEMORY, otherwise the concrete resource.

AuthorizationCheckResult

One advisory decision; false covers both an absent target and an authorization denial.

Field	Type	Required	Description
`allowed`	`boolean`	yes	Whether the caller currently has effective authority.

AuthorizationGrant

Current or historical direct authorization grant.

Field	Type	Required	Description
`grantId`	`string`	yes	Durable grant UUID.
`audience`	`GrantAudience`	yes	Grant audience.
`rule`	`AccessPolicyRule`	yes	Granted authorization descriptor.
`createdAt`	`number`	yes	Creation time in epoch milliseconds.
`createdById`	`string`	yes	Exact audit actor that created the grant.
`revokedAt`	`number \| null`	no	Revocation time in epoch milliseconds, when revoked.
`revokedById`	`string \| null`	no	Exact audit actor that revoked the grant, when revoked.

CheckAuthorizationsRequest

Evaluates between 1 and 50 concrete authorization checks.

Field	Type	Required	Description
`checks`	`Array<AuthorizationCheck>`	yes	Concrete checks evaluated in request order.

CheckAuthorizationsResponse

Positional advisory authorization results.

Field	Type	Required	Description
`results`	`Array<AuthorizationCheckResult>`	yes	Results corresponding one-for-one with the request checks.

CreateAuthorizationGrantRequest

Creates one live direct authorization grant.

Field	Type	Required	Description
`grantId`	`string \| null`	no	Optional caller-provided grant UUID.
`audience`	`GrantAudience`	yes	Audience receiving the grant.
`rule`	`AccessPolicyRule`	yes	Authorization descriptor to grant.

GrantAudience

Exactly one principal or the all-authenticated audience.

Field	Type	Required	Description
`principalId`	`string \| null`	no	Active HUMAN or SERVICE principal UUID.
`allAuthenticated`	`GrantAudienceAllAuthenticated \| null`	no	Set to true to address every authenticated principal.

ListAuthorizationGrantsResponse

One page of direct authorization grants.

Field	Type	Required	Description
`grants`	`Array<AuthorizationGrant>`	yes	Grant rows in stable creation order.
`nextToken`	`string \| null`	no	Opaque continuation token, omitted on the final page.

ListRoleAssignmentsResponse

One page of scoped role assignments.

Field	Type	Required	Description
`roleAssignments`	`Array<RoleAssignment>`	yes	Role assignments in stable assignment order.
`nextToken`	`string \| null`	no	Opaque continuation token, omitted on the final page.

RoleAssignment

Current or historical scoped role assignment.

Field	Type	Required	Description
`roleAssignmentId`	`string`	yes	Durable role-assignment UUID.
`principalId`	`string`	yes	Assigned principal UUID.
`role`	`Role`	yes	Code-defined assigned role.
`assignedResource`	`RoleAssignmentTarget`	yes	INSTANCE or SPACE assignment boundary.
`assignedAt`	`number`	yes	Assignment time in epoch milliseconds.
`assignedById`	`string`	yes	Exact audit actor that assigned the role.
`revokedAt`	`number \| null`	no	Revocation time in epoch milliseconds, when revoked.
`revokedById`	`string \| null`	no	Exact audit actor that revoked the assignment, when revoked.

RoleAssignmentTarget

An INSTANCE or SPACE role-assignment boundary. resourceId is omitted for INSTANCE and required for SPACE.

Field	Type	Required	Description
`kind`	`"INSTANCE" \| "SPACE"`	yes	Role-assignment target kind.
`resourceId`	`string \| null`	no	Memory-space UUID; omitted for the singleton INSTANCE target.

Response Shapes

Response shape types model values returned by the SDK after forward-compatible unknown enum strings are coerced to null.

AuthorizationCheckResultResponseShape

Field	Type	Required	Description
`allowed`	`boolean`	yes	Whether the caller currently has effective authority.

AuthorizationGrantResponseShape

Field	Type	Required	Description
`grantId`	`string`	yes	Durable grant UUID.
`audience`	`GrantAudienceResponseShape`	yes	Grant audience.
`rule`	`AccessPolicyRuleResponseShape`	yes	Granted authorization descriptor.
`createdAt`	`number`	yes	Creation time in epoch milliseconds.
`createdById`	`string`	yes	Exact audit actor that created the grant.
`revokedAt`	`number \| null`	no	Revocation time in epoch milliseconds, when revoked.
`revokedById`	`string \| null`	no	Exact audit actor that revoked the grant, when revoked.

CheckAuthorizationsResponseShape

Field	Type	Required	Description
`results`	`Array<AuthorizationCheckResultResponseShape>`	yes	Results corresponding one-for-one with the request checks.

GrantAudienceResponseShape

Type constraint: GrantAudienceResponseShape = RequireExactlyOne<GrantAudienceResponseShapeBase, "allAuthenticated" \| "principalId">

Field	Type	Required	Description
`principalId`	`string \| null`	no	Active HUMAN or SERVICE principal UUID.
`allAuthenticated`	`GrantAudienceAllAuthenticated \| null`	no	Set to true to address every authenticated principal.

ListAuthorizationGrantsResponseShape

Field	Type	Required	Description
`grants`	`Array<AuthorizationGrantResponseShape>`	yes	Grant rows in stable creation order.
`nextToken`	`string \| null`	no	Opaque continuation token, omitted on the final page.

ListRoleAssignmentsResponseShape

Field	Type	Required	Description
`roleAssignments`	`Array<RoleAssignmentResponseShape>`	yes	Role assignments in stable assignment order.
`nextToken`	`string \| null`	no	Opaque continuation token, omitted on the final page.

RoleAssignmentResponseShape

Field	Type	Required	Description
`roleAssignmentId`	`string`	yes	Durable role-assignment UUID.
`principalId`	`string`	yes	Assigned principal UUID.
`role`	`Role \| null`	yes	Code-defined assigned role.
`assignedResource`	`RoleAssignmentTargetResponseShape`	yes	INSTANCE or SPACE assignment boundary.
`assignedAt`	`number`	yes	Assignment time in epoch milliseconds.
`assignedById`	`string`	yes	Exact audit actor that assigned the role.
`revokedAt`	`number \| null`	no	Revocation time in epoch milliseconds, when revoked.
`revokedById`	`string \| null`	no	Exact audit actor that revoked the assignment, when revoked.

RoleAssignmentTargetResponseShape

Field	Type	Required	Description
`kind`	`"INSTANCE" \| "SPACE" \| null`	yes	Role-assignment target kind.
`resourceId`	`string \| null`	no	Memory-space UUID; omitted for the singleton INSTANCE target.

Access Policy

On this page