Policies

Define allow/deny authorization policies to control agent access.

Overview

The policies sub-client lets you create declarative authorization policies that control when and how agents can use their grants. Policies support scope-based rules, time-of-day restrictions, and priority-based evaluation.

const policy = await grantex.policies.create({
  name: 'business-hours-only',
  effect: 'deny',
  priority: 10,
  timeOfDayStart: '18:00',
  timeOfDayEnd: '09:00',
});

---

policies.create()

Create a new authorization policy.

const policy = await grantex.policies.create({
  name: 'deny-payments-after-hours',
  effect: 'deny',
  priority: 10,
  scopes: ['payments:initiate'],
  timeOfDayStart: '18:00',
  timeOfDayEnd: '06:00',
});

console.log(policy.id);       // 'pol_01HXYZ...'
console.log(policy.name);     // 'deny-payments-after-hours'
console.log(policy.effect);   // 'deny'
console.log(policy.priority); // 10

Parameters

name · string · required

Human-readable name for the policy.

effect · 'allow' | 'deny' · required

Whether this policy allows or denies matching requests.

priority · number

Evaluation priority. Higher-priority policies are evaluated first. Defaults to server-assigned value.

agentId · string

Restrict the policy to a specific agent.

principalId · string

Restrict the policy to a specific user.

scopes · string[]

The scopes this policy applies to. If omitted, the policy applies to all scopes.

timeOfDayStart · string

Start time for a time-of-day restriction (24h format, e.g. '09:00').

timeOfDayEnd · string

End time for a time-of-day restriction (24h format, e.g. '18:00').

Response: Policy

id · string

Unique policy identifier.

name · string

Policy name.

effect · string

'allow' or 'deny'.

priority · number

Evaluation priority.

agentId · string | null

Restricted agent ID, or null for all agents.

principalId · string | null

Restricted user ID, or null for all users.

scopes · string[] | null

Restricted scopes, or null for all scopes.

timeOfDayStart · string | null

Time-of-day restriction start (24h format).

timeOfDayEnd · string | null

Time-of-day restriction end (24h format).

createdAt · string

ISO 8601 creation timestamp.

updatedAt · string

ISO 8601 last-updated timestamp.

---

policies.list()

List all policies for your organization.

const result = await grantex.policies.list();

console.log(result.total); // 5
for (const policy of result.policies) {
  console.log(`${policy.name}: ${policy.effect} (priority ${policy.priority})`);
}

Response: ListPoliciesResponse

policies · Policy[]

Array of policy objects.

total · number

Total number of policies.

---

policies.get()

Retrieve a single policy by its ID.

const policy = await grantex.policies.get('pol_01HXYZ...');

console.log(policy.name);           // 'deny-payments-after-hours'
console.log(policy.timeOfDayStart); // '18:00'
console.log(policy.timeOfDayEnd);   // '06:00'

Parameters

policyId · string · required

The policy ID to retrieve.

Response

Returns a Policy object.

---

policies.update()

Update an existing policy. Only the provided fields are modified.

const updated = await grantex.policies.update('pol_01HXYZ...', {
  name: 'deny-payments-overnight',
  timeOfDayStart: '22:00',
  timeOfDayEnd: '06:00',
});

console.log(updated.name);           // 'deny-payments-overnight'
console.log(updated.timeOfDayStart); // '22:00'

Parameters

policyId · string · required

The policy ID to update.

name · string

New policy name.

effect · 'allow' | 'deny'

New effect.

priority · number

New priority.

agentId · string | null

New agent restriction. Pass null to clear.

principalId · string | null

New user restriction. Pass null to clear.

scopes · string[] | null

New scope restriction. Pass null to clear.

timeOfDayStart · string | null

New time-of-day start. Pass null to clear.

timeOfDayEnd · string | null

New time-of-day end. Pass null to clear.

Response

Returns the updated Policy object.

---

policies.delete()

Delete a policy.

await grantex.policies.delete('pol_01HXYZ...');
// Returns void -- the policy is removed

Parameters

policyId · string · required

The policy ID to delete.

Response

Returns void.