Policies

Overview

Policies provide fine-grained access control rules that are evaluated during authorization. Each policy has an effect (allow or deny), a priority, and optional filters for agent, principal, scopes, and time-of-day restrictions. Access the policies client via client.policies.

Create

Create a new authorization policy:

from grantex import Grantex, CreatePolicyParams

with Grantex(api_key="gx_live_...") as client:
    policy = client.policies.create(CreatePolicyParams(
        name="business-hours-only",
        effect="deny",
        priority=10,
        agent_id="agt_abc123",
        time_of_day_start="18:00",
        time_of_day_end="08:00",
    ))

    print(f"Policy ID: {policy.id}")
    print(f"Effect: {policy.effect}")
    print(f"Priority: {policy.priority}")

CreatePolicyParams

Field	Type	Required	Default	Description
`name`	`str`	Yes	—	Human-readable name for the policy.
`effect`	`str`	Yes	—	`"allow"` or `"deny"`.
`priority`	`int`	No	`0`	Higher priority policies are evaluated first.
`agent_id`	`str \| None`	No	`None`	Restrict to a specific agent.
`principal_id`	`str \| None`	No	`None`	Restrict to a specific principal (user).
`scopes`	`list[str] \| None`	No	`None`	Restrict to specific scopes.
`time_of_day_start`	`str \| None`	No	`None`	Start of allowed/denied time window (`HH:MM`).
`time_of_day_end`	`str \| None`	No	`None`	End of allowed/denied time window (`HH:MM`).

List

List all policies for your developer account:

from grantex import Grantex

with Grantex(api_key="gx_live_...") as client:
    result = client.policies.list()

    print(f"Total policies: {result.total}")
    for policy in result.policies:
        print(f"  {policy.name}: {policy.effect} (priority {policy.priority})")

ListPoliciesResponse

Field	Type	Description
`policies`	`tuple[Policy, ...]`	The list of policies.
`total`	`int`	Total number of policies.

Get

Retrieve a single policy by its ID:

policy = client.policies.get("pol_abc123")

print(f"Name: {policy.name}")
print(f"Effect: {policy.effect}")
print(f"Agent: {policy.agent_id}")
print(f"Scopes: {policy.scopes}")
print(f"Time window: {policy.time_of_day_start} - {policy.time_of_day_end}")

Update

Update an existing policy. Only fields you provide will be modified:

from grantex import Grantex, UpdatePolicyParams

with Grantex(api_key="gx_live_...") as client:
    updated = client.policies.update(
        "pol_abc123",
        UpdatePolicyParams(
            name="business-hours-only-v2",
            priority=20,
            time_of_day_start="19:00",
            time_of_day_end="07:00",
        ),
    )

    print(f"Updated at: {updated.updated_at}")

UpdatePolicyParams

Field	Type	Required	Description
`name`	`str \| None`	No	New name for the policy.
`effect`	`str \| None`	No	New effect (`"allow"` or `"deny"`).
`priority`	`int \| None`	No	New priority value.
`agent_id`	`str \| None`	No	New agent filter.
`principal_id`	`str \| None`	No	New principal filter.
`scopes`	`list[str] \| None`	No	New scope filter.
`time_of_day_start`	`str \| None`	No	New time window start (`HH:MM`).
`time_of_day_end`	`str \| None`	No	New time window end (`HH:MM`).

Delete

Delete a policy by its ID:

client.policies.delete("pol_abc123")
# Returns None on success

Policy Type

The Policy frozen dataclass has the following fields:

Field	Type	Description
`id`	`str`	Unique policy identifier.
`name`	`str`	Human-readable policy name.
`effect`	`str`	`"allow"` or `"deny"`.
`priority`	`int`	Evaluation priority (higher = first).
`agent_id`	`str \| None`	Agent filter (if set).
`principal_id`	`str \| None`	Principal filter (if set).
`scopes`	`tuple[str, ...] \| None`	Scope filter (if set).
`time_of_day_start`	`str \| None`	Time window start.
`time_of_day_end`	`str \| None`	Time window end.
`created_at`	`str`	ISO 8601 creation timestamp.
`updated_at`	`str`	ISO 8601 last-updated timestamp.

Example: Common Policy Patterns

Deny After Hours

from grantex import Grantex, CreatePolicyParams

with Grantex(api_key="gx_live_...") as client:
    client.policies.create(CreatePolicyParams(
        name="deny-after-hours",
        effect="deny",
        priority=100,
        time_of_day_start="20:00",
        time_of_day_end="06:00",
    ))

Allow Specific Scopes for an Agent

from grantex import Grantex, CreatePolicyParams

with Grantex(api_key="gx_live_...") as client:
    client.policies.create(CreatePolicyParams(
        name="read-only-for-assistant",
        effect="allow",
        priority=50,
        agent_id="agt_abc123",
        scopes=["files:read", "calendar:read"],
    ))

Deny a Specific User

from grantex import Grantex, CreatePolicyParams

with Grantex(api_key="gx_live_...") as client:
    client.policies.create(CreatePolicyParams(
        name="block-suspended-user",
        effect="deny",
        priority=200,
        principal_id="user_suspended_xyz",
    ))

Overview

Authorization

Resources

Enforcement

Reference

Overview

Create

CreatePolicyParams

List

ListPoliciesResponse

Get

Update

UpdatePolicyParams

Delete

Policy Type

Example: Common Policy Patterns

Deny After Hours

Allow Specific Scopes for an Agent

Deny a Specific User

​Overview

​Create

​CreatePolicyParams

​List

​ListPoliciesResponse

​Get

​Update

​UpdatePolicyParams

​Delete

​Policy Type

​Example: Common Policy Patterns

​Deny After Hours

​Allow Specific Scopes for an Agent

​Deny a Specific User

Overview

Create

CreatePolicyParams

List

ListPoliciesResponse

Get

Update

UpdatePolicyParams

Delete

Policy Type

Example: Common Policy Patterns

Deny After Hours

Allow Specific Scopes for an Agent

Deny a Specific User