Skip to content
Hexel StudioDocs

Policies and approvals

Allow an agent's tools in your deployment's policy, make its writes wait for an approver, and save the change safely with the SDK or the API.

On this page

Each Titan deployment has one policy. It decides, for every capability call an agent makes, whether the call runs, is refused, or waits for people to approve it. This guide edits that policy with the TypeScript SDK, and shows the same change over HTTP.

How a policy decides

  • Deny by default. A call that no rule matches is refused. A new deployment starts with one rule, deny-all, that denies everything.
  • Deny wins. Rules combine as deny over require approval over allow, whatever their priorities. A matching deny rule refuses the call even when an allow rule also matches. That is why allowing anything means removing deny-all; everything you don't allow is still denied by default.
  • Some calls always need approval. A call that changes something in an organization tool (a write) is never run on an allow rule alone. It needs a require_approval rule that names approvers.

A rule matches on capability ids or toolkits, and can narrow the match to workspaces, environments, agents, side-effect classes or a minimum agent assurance level. An organization tool's capability id is <organization_id>.<toolkit>.<tool>.

Before you start

  • The deployment's id (td-..., the id from listDeployments). Management routes take this id.
  • Permissions in your organization: titan:enforcement_deployment:read to read the policy and titan:enforcement_deployment:create to change it.
  • For approvals: the user ids of the people who may approve. Each of them also needs titan:approval:decide (and titan:approval:read to list requests).

Allow reads

allowInPolicy reads the policy, adds an allow rule, removes deny-all and saves the result with the next revision:

TypeScript
import { configure } from '@hexelstudio/titan-sdk';
import { allowInPolicy } from '@hexelstudio/titan-sdk/flows';

configure({ baseURL: 'https://api.hexelstudio.com/v1', apiKey: process.env.HEXEL_API_KEY });

await allowInPolicy(deploymentId, {
  ruleId: 'allow-github-reads',
  capabilityIds: ['github.issue.get', 'github.issue.list'],
  workspaceIds: [workspaceId],
  environmentIds: [environmentId],
});

When you name environments, the rule matches only while they are active; a frozen environment's calls are not allowed by it. Use toolkits: ['ACME_CRM'] instead of capabilityIds to match every capability of a toolkit.

Require approval for writes

Pass approvers and allowInPolicy writes a require_approval rule instead, together with an approval role and an approval profile:

TypeScript
await allowInPolicy(deploymentId, {
  ruleId: 'approve-acme-writes',
  toolkits: ['ACME_CRM'],
  sideEffectClasses: ['non_idempotent_side_effect'],
  approvers: {
    roleId: 'tool-approvers',
    profileId: 'tool-writes',
    humanPrincipalIds: [approverUserId],
    quorum: 1,                       // approvals each call needs, 1 to 8
    requesterSeparationRequired: true, // the requester can't approve their own call (the default)
  },
});
Approver optionDefaultMeaning
humanPrincipalIdsrequiredUser ids of the people in the approval role.
quorum1How many approvals complete a request, 1 to 8.
maximumAgeSeconds3600How long a request may stay open, 60 to 604800 seconds. A request not tied to a durable session still ends within 24 hours.
requesterSeparationRequiredtrueThe person who made the request can't approve it.
delegatorSeparationRequiredfalseThe person the agent acts for can't approve it.

Unless the agent runs in a durable session, a request also expires when the agent's current runtime token does, so on Titan Cloud it has to be decided within a few minutes. See Approvals for how a request is decided and what the agent sees.

Make any other change

editPolicy reads the current policy, passes it to your function and saves what it returns. Build the change with the policy builders, which produce exactly what Titan's policy compiler accepts (every rule complete, lists sorted, the revision bumped):

TypeScript
import { editPolicy, upsertRules, removeRules, denyRule } from '@hexelstudio/titan-sdk/flows';

// Deny one capability everywhere, keeping every other rule.
await editPolicy(deploymentId, source =>
  upsertRules(source, [denyRule({ ruleId: 'deny-deletes', capabilityIds: [deleteCapabilityId] })]));

// Remove rules. Removing the last rule puts deny-all back.
await editPolicy(deploymentId, source => removeRules(source, ['allow-github-reads']));

Use allowRule, denyRule, requireApprovalRule and withApprovers to build rules yourself, and upsertRules to add or replace them by rule_id.

What happens when you save

On Titan Cloud, Titan signs and publishes the policy when you save it; there is no separate publish step. Titan checks the new policy before it accepts it:

Status and codeWhyWhat to do
409 POLICY_REVISION_STALEsource_revision isn't greater than the policy in force. Someone else saved a change after you read it.Read the policy again, reapply your change, save. editPolicy reads fresh each time it runs.
400 POLICY_INVALIDThe policy doesn't compile, names another organization or deployment, or doesn't combine with your organization's policy layers.Fix the policy.
400 POLICY_TERM_UNSUPPORTEDA rule uses a limit or obligation Titan can't enforce yet.Remove that term.
400 OBLIGATION_PROFILE_UNKNOWNA rule refers to an obligation profile that isn't installed on the deployment.Install the profile first, or remove the reference.
409 DEPLOYMENT_NOT_PROVISIONED, 409 DEPLOYMENT_RETIREDThe deployment isn't ready, or is retired.Wait for provisioning, or use another deployment.

Saving the policy already in force again changes nothing.

Over HTTP

Read the policy, then send the whole source back with your change and a greater source_revision:

Bash
curl https://api.hexelstudio.com/v1/titan/management/deployments/$DEPLOYMENT_ID/policy \
  -H "X-API-Key: $HEXEL_API_KEY"

The response has the source, its source_revision, and the enforcement_deployment_id that administration calls name in Titan-Enforcement-Deployment.

Bash
curl -X PUT https://api.hexelstudio.com/v1/titan/management/deployments/$DEPLOYMENT_ID/policy \
  -H "X-API-Key: $HEXEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d @policy.json

The policy compiler is strict: every rule needs all of its fields (rule_id, effect, priority, match, approval_profile_ids, connection_constraints, limits, obligations), rules are sorted by rule_id, and id lists are sorted with no duplicates. The SDK's builders do this for you.