Access Policy — Java SDK

Java SDK reference for authorization policy: direct grants, scoped roles, and authorization checks.

Methods on this page are called as client.access_policy.<method>(...) on a Goodmem instance.

Class — ai.pairsys.goodmem.client.api.AccessPolicyAPI (extends internal AccessPolicyAPIBase).

import ai.pairsys.goodmem.client.Goodmem;

try (Goodmem client = Goodmem.builder()
        .baseUrl("http://localhost:8080")
        .apiKey("gm_...")
        .build()) {
    // client.access_policy.<method>(...)
}

Async variants

Every method listed below also exists on ai.pairsys.goodmem.client.api.AsyncAccessPolicyAPI (accessed via asyncClient.access_policy on an AsyncGoodmem) with the same parameter list, wrapped in CompletableFuture<T>. Paginated list methods return CompletableFuture<AsyncPage<T>>. See the async client guide for composition patterns.

import ai.pairsys.goodmem.client.AsyncGoodmem;

try (AsyncGoodmem asyncClient = AsyncGoodmem.builder()
        .baseUrl("http://localhost:8080")
        .apiKey("gm_...")
        .build()) {
    asyncClient.access_policy.<method>(...)  // returns CompletableFuture<T>
}

Method Summary

Modifier and Type	Method	Description
`CheckAuthorizationsResponse`	`check(CheckAuthorizationsRequest)`	Check effective authorization
`AuthorizationGrant`	`grantsCreate(CreateAuthorizationGrantRequest)`	Create an authorization grant
`AuthorizationGrant`	`grantsDelete(String)`	Revoke an authorization grant
`AuthorizationGrant`	`grantsGet(String, Map<String, Object>)`	Get an authorization grant
`Page<AuthorizationGrant>`	`grantsList(Map<String, Object>)`	List authorization grants
`RoleAssignment`	`roleAssignmentsCreate(AssignRoleRequest)`	Assign a scoped role
`RoleAssignment`	`roleAssignmentsDelete(String)`	Revoke a scoped role assignment
`RoleAssignment`	`roleAssignmentsGet(String, Map<String, Object>)`	Get a scoped role assignment
`Page<RoleAssignment>`	`roleAssignmentsList(Map<String, Object>)`	List scoped role assignments

Method Detail

`check(CheckAuthorizationsRequest)`

CheckAuthorizationsResponse check(CheckAuthorizationsRequest request)

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 and LIST_API_KEY target INSTANCE; CREATE_MEMORY and LIST_MEMORY target their parent SPACE; reads, mutations, proxy operations, and access-policy administration target concrete resources. LIST_RETRIEVE_MEMORY_LOG_POLICY is rejected because its current candidate-based list rule has no instance-wide preflight.

HTTP: POST /v1/access-policy:check

Parameters:

request (CheckAuthorizationsRequest) — full request payload. The linked Javadoc lists every field and its Builder setter.

Returns: CheckAuthorizationsResponse

Throws:

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

See Also:

AccessPolicyAPIBase.check(CheckAuthorizationsRequest) on javadoc.io

Example

CheckAuthorizationsResponse checkAuthorizationsResponse = client.access_policy.check(CheckAuthorizationsRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X POST 'http://localhost:8080/v1/access-policy:check' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "checks": [
      {
        "operation": "READ_INSTANCE",
        "target": {
          "kind": "INSTANCE"
        }
      }
    ]
  }'

`grantsCreate(CreateAuthorizationGrantRequest)`

AuthorizationGrant grantsCreate(CreateAuthorizationGrantRequest request)

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:

request (CreateAuthorizationGrantRequest) — full request payload. The linked Javadoc lists every field and its Builder setter.

Returns: AuthorizationGrant

Throws:

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

See Also:

AccessPolicyAPIBase.grantsCreate(CreateAuthorizationGrantRequest) on javadoc.io

Example

AuthorizationGrant authorizationGrant = client.access_policy.grantsCreate(CreateAuthorizationGrantRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X POST 'http://localhost:8080/v1/access-policy/grants' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{ /* CreateAuthorizationGrantRequest fields, see Javadoc */ }'

`grantsDelete(String)`

AuthorizationGrant grantsDelete(String id)

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:

id (String) — Grant UUID

Returns: AuthorizationGrant

Throws:

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

See Also:

AccessPolicyAPIBase.grantsDelete(String) on javadoc.io

Example

AuthorizationGrant authorizationGrant = client.access_policy.grantsDelete("...");

REST equivalent

curl -X DELETE 'http://localhost:8080/v1/access-policy/grants/{id}' \
  -H "x-api-key: gm_..."

`grantsGet(String, Map<String, Object>)`

AuthorizationGrant grantsGet(String id, Map<String, Object> query)

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:

id (String) — Grant UUID
query (Map<String, Object>) — query-string parameters; use Map.of() when none.

Returns: AuthorizationGrant

Throws:

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

See Also:

AccessPolicyAPIBase.grantsGet(String, Map<String, Object>) on javadoc.io

Example

AuthorizationGrant authorizationGrant = client.access_policy.grantsGet("...", java.util.Map.of());

REST equivalent

curl -X GET 'http://localhost:8080/v1/access-policy/grants/{id}' \
  -H "x-api-key: gm_..."

`grantsList(Map<String, Object>)`

Page<AuthorizationGrant> grantsList(Map<String, Object> query)

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:

query (Map<String, Object>) — query-string parameters; use Map.of() when none.

Returns: Page<AuthorizationGrant>

Throws:

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

See Also:

AccessPolicyAPIBase.grantsList(Map<String, Object>) on javadoc.io

Example

Page<AuthorizationGrant> page = client.access_policy.grantsList(java.util.Map.of());

REST equivalent

curl -X GET 'http://localhost:8080/v1/access-policy/grants' \
  -H "x-api-key: gm_..."

`roleAssignmentsCreate(AssignRoleRequest)`

RoleAssignment roleAssignmentsCreate(AssignRoleRequest request)

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:

request (AssignRoleRequest) — full request payload. The linked Javadoc lists every field and its Builder setter.

Returns: RoleAssignment

Throws:

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

See Also:

AccessPolicyAPIBase.roleAssignmentsCreate(AssignRoleRequest) on javadoc.io

Example

RoleAssignment roleAssignment = client.access_policy.roleAssignmentsCreate(AssignRoleRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X POST 'http://localhost:8080/v1/access-policy/role-assignments' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{ /* AssignRoleRequest fields, see Javadoc */ }'

`roleAssignmentsDelete(String)`

RoleAssignment roleAssignmentsDelete(String id)

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:

id (String) — Role-assignment UUID

Returns: RoleAssignment

Throws:

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

See Also:

AccessPolicyAPIBase.roleAssignmentsDelete(String) on javadoc.io

Example

RoleAssignment roleAssignment = client.access_policy.roleAssignmentsDelete("...");

REST equivalent

curl -X DELETE 'http://localhost:8080/v1/access-policy/role-assignments/{id}' \
  -H "x-api-key: gm_..."

`roleAssignmentsGet(String, Map<String, Object>)`

RoleAssignment roleAssignmentsGet(String id, Map<String, Object> query)

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:

id (String) — Role-assignment UUID
query (Map<String, Object>) — query-string parameters; use Map.of() when none.

Returns: RoleAssignment

Throws:

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

See Also:

AccessPolicyAPIBase.roleAssignmentsGet(String, Map<String, Object>) on javadoc.io

Example

RoleAssignment roleAssignment = client.access_policy.roleAssignmentsGet("...", java.util.Map.of());

REST equivalent

curl -X GET 'http://localhost:8080/v1/access-policy/role-assignments/{id}' \
  -H "x-api-key: gm_..."

`roleAssignmentsList(Map<String, Object>)`

Page<RoleAssignment> roleAssignmentsList(Map<String, Object> query)

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:

query (Map<String, Object>) — query-string parameters; use Map.of() when none.

Returns: Page<RoleAssignment>

Throws:

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

See Also:

AccessPolicyAPIBase.roleAssignmentsList(Map<String, Object>) on javadoc.io

Example

Page<RoleAssignment> page = client.access_policy.roleAssignmentsList(java.util.Map.of());

REST equivalent

curl -X GET 'http://localhost:8080/v1/access-policy/role-assignments' \
  -H "x-api-key: gm_..."

Errors

Every method on this page may throw the standard HTTP-error class hierarchy rooted at GoodmemException:

BadRequestException (400), AuthenticationException (401), PermissionDeniedException (403), NotFoundException (404), ConflictException (409), UnprocessableEntityException (422), RateLimitException (429), InternalServerException (5xx), or the generic ApiException for any other 4xx/5xx. All are unchecked (RuntimeException). See Errors.

All error classes live in ai.pairsys.goodmem.client.errors and are unchecked (RuntimeException). Async siblings complete the returned CompletableFuture exceptionally with the same types, wrapped in CompletionException at await time. See Errors on the index for the full table.

AccessPolicy

On this page