Access Policy

Methods on this page are called as client.access_policy.<method>(...) where client is either a synchronous Goodmem or asynchronous AsyncGoodmem instance initialized below:

from goodmem import Goodmem
client = Goodmem(base_url='http://localhost:8080', api_key='gm_...')

from goodmem import AsyncGoodmem
client = AsyncGoodmem(base_url='http://localhost:8080', api_key='gm_...')

Check effective authorization

access_policy.check(*, checks: list[AuthorizationCheck]) → CheckAuthorizationsResponse

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.

Parameters:

checks (list[AuthorizationCheck]) — Concrete checks evaluated in request order.

Returns:

CheckAuthorizationsResponse

Raises:

APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

decisions = client.access_policy.check(
    checks=[
        AuthorizationCheck(
            operation="READ_INSTANCE",
            target=AccessPolicyTarget(kind="INSTANCE"),
        )
    ]
)
print(decisions.results[0].allowed)

Create an authorization grant

access_policy.grants.create(*, audience: GrantAudience, rule: AccessPolicyRule, grant_id: str = None) → AuthorizationGrant

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.

Parameters:

audience (GrantAudience) — Audience receiving the grant.
rule (AccessPolicyRule) — Authorization descriptor to grant.
grant_id (str, format: uuid, optional) — Optional caller-provided grant UUID.

Returns:

AuthorizationGrant

Raises:

PermissionDeniedError — The caller lacks the permission the operation requires.
APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

grant = client.access_policy.grants.create(
    audience=GrantAudience(principal_id=principal_id),
    rule=AccessPolicyRule(
        operation="READ_SPACE",
        selector="EXACT",
        assigned_resource=AccessPolicyTarget(
            kind="SPACE",
            resource_id=space_id,
        ),
    ),
)

Revoke an authorization grant

access_policy.grants.delete(*, id: str) → AuthorizationGrant

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

Parameters:

id (str) — Grant UUID

Returns:

AuthorizationGrant

Raises:

APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

revoked_grant = client.access_policy.grants.delete(id=grant.grant_id)

Get an authorization grant

access_policy.grants.get(*, id: str, include_revoked: bool = None) → AuthorizationGrant

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

Parameters:

id (str) — Grant UUID
include_revoked (bool, optional, server default=False) — Include a revoked historical row

Returns:

AuthorizationGrant

Raises:

PermissionDeniedError — The caller lacks the permission the operation requires.
APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

fetched_grant = client.access_policy.grants.get(id=grant.grant_id)

List authorization grants

access_policy.grants.list(*, resource_kind: str, include_revoked: bool = None, max_results: int = None, next_token: str = None, resource_id: str = None) → ListAuthorizationGrantsResponse

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

Parameters:

resource_kind (str) — Required target resource kind
include_revoked (bool, optional, server default=False) — Include revoked history
max_results (int, format: int32, optional, server default=50) — Page size; 0 or omission uses the default of 50, maximum 1,000
next_token (str, optional) — Opaque continuation token
resource_id (str, optional) — Required target UUID except when resource_kind is INSTANCE

Returns:

ListAuthorizationGrantsResponse

Raises:

APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

grants = client.access_policy.grants.list(
    resource_kind="SPACE",
    resource_id=space_id,
)
for visible_grant in grants:
    print(visible_grant.grant_id)

Assign a scoped role

access_policy.role_assignments.create(*, assigned_resource: RoleAssignmentTarget, principal_id: str, role: str, role_assignment_id: str = None) → RoleAssignment

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.

Parameters:

assigned_resource (RoleAssignmentTarget) — INSTANCE or SPACE boundary receiving the assignment.
principal_id (str, format: uuid) — Active principal receiving the role.
role (str) — Code-defined non-ROOT role to assign.
role_assignment_id (str, format: uuid, optional) — Optional caller-provided role-assignment UUID.

Returns:

RoleAssignment

Raises:

PermissionDeniedError — The caller lacks the permission the operation requires.
APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

assignment = client.access_policy.role_assignments.create(
    principal_id=principal_id,
    role="SPACE_VIEWER",
    assigned_resource=RoleAssignmentTarget(
        kind="SPACE",
        resource_id=space_id,
    ),
)

Revoke a scoped role assignment

access_policy.role_assignments.delete(*, id: str) → RoleAssignment

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

Parameters:

id (str) — Role-assignment UUID

Returns:

RoleAssignment

Raises:

APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

revoked_assignment = client.access_policy.role_assignments.delete(
    id=assignment.role_assignment_id
)

Get a scoped role assignment

access_policy.role_assignments.get(*, id: str, include_revoked: bool = None) → RoleAssignment

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

Parameters:

id (str) — Role-assignment UUID
include_revoked (bool, optional, server default=False) — Include a revoked historical row

Returns:

RoleAssignment

Raises:

PermissionDeniedError — The caller lacks the permission the operation requires.
APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

fetched_assignment = client.access_policy.role_assignments.get(
    id=assignment.role_assignment_id
)

List scoped role assignments

access_policy.role_assignments.list(*, resource_kind: str, include_revoked: bool = None, max_results: int = None, next_token: str = None, resource_id: str = None) → ListRoleAssignmentsResponse

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

Parameters:

resource_kind (str) — Required INSTANCE or SPACE kind
include_revoked (bool, optional, server default=False) — Include revoked history
max_results (int, format: int32, optional, server default=50) — Page size; 0 or omission uses the default of 50, maximum 1,000
next_token (str, optional) — Opaque continuation token
resource_id (str, optional) — Required space UUID; omitted for INSTANCE

Returns:

ListRoleAssignmentsResponse

Raises:

PermissionDeniedError — The caller lacks the permission the operation requires.
APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

assignments = client.access_policy.role_assignments.list(
    resource_kind="SPACE",
    resource_id=space_id,
)
for visible_assignment in assignments:
    print(visible_assignment.role_assignment_id)

Async usage: client.access_policy exposes the same methods on AsyncGoodmem; use await / async for as needed.

Data Models

All data models are pydantic v2 models. Fields are shown with their Python attribute names; JSON responses use camelCase aliases (e.g., owner_id → ownerId).

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.

operation (Operation | None) — Operation the caller proposes to perform.
target (AccessPolicyTarget) — Target required by the operation: INSTANCE for top-level creates, parent SPACE for CREATE_MEMORY or LIST_MEMORY, otherwise the concrete resource.

CheckAuthorizationsResponse

Positional advisory authorization results.

results (list[AuthorizationCheckResult]) — Results corresponding one-for-one with the request checks.

AuthorizationCheckResult

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

allowed (bool) — Whether the caller currently has effective authority.

GrantAudience

Exactly one principal or the all-authenticated audience.

principal_id (str, optional) — Active HUMAN or SERVICE principal UUID.
all_authenticated (GrantAudienceAllAuthenticated, optional) — Set to true to address every authenticated principal.

GrantAudienceAllAuthenticated

String enum: "True"

AuthorizationGrant

Current or historical direct authorization grant.

grant_id (str) — Durable grant UUID.
audience (GrantAudience) — Grant audience.
rule (AccessPolicyRule) — Granted authorization descriptor.
created_at (int) — Creation time in epoch milliseconds.
created_by_id (str) — Exact audit actor that created the grant.
revoked_at (int, optional) — Revocation time in epoch milliseconds, when revoked.
revoked_by_id (str, optional) — Exact audit actor that revoked the grant, when revoked.

ListAuthorizationGrantsResponse

One page of direct authorization grants.

grants (list[AuthorizationGrant]) — Grant rows in stable creation order.
next_token (str, optional) — Opaque continuation token, omitted on the final page.

RoleAssignmentTarget

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

kind (Optional[Literal['INSTANCE', 'SPACE']]) — Role-assignment target kind.
resource_id (str, optional) — Memory-space UUID; omitted for the singleton INSTANCE target.

RoleAssignment

Current or historical scoped role assignment.

role_assignment_id (str) — Durable role-assignment UUID.
principal_id (str) — Assigned principal UUID.
role (Role | None) — Code-defined assigned role.
assigned_resource (RoleAssignmentTarget) — INSTANCE or SPACE assignment boundary.
assigned_at (int) — Assignment time in epoch milliseconds.
assigned_by_id (str) — Exact audit actor that assigned the role.
revoked_at (int, optional) — Revocation time in epoch milliseconds, when revoked.
revoked_by_id (str, optional) — Exact audit actor that revoked the assignment, when revoked.

Role

String enum: "ROOT" · "ADMIN" · "USER" · "SPACE_VIEWER" · "SPACE_CONTRIBUTOR" · "SPACE_CONTENT_MANAGER" · "SPACE_ADMIN"

ListRoleAssignmentsResponse

One page of scoped role assignments.

role_assignments (list[RoleAssignment]) — Role assignments in stable assignment order.
next_token (str, optional) — Opaque continuation token, omitted on the final page.

Access Policy

On this page