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_approvalrule 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-..., theidfromlistDeployments). Management routes take this id. - Permissions in your organization:
titan:enforcement_deployment:readto read the policy andtitan:enforcement_deployment:createto change it. - For approvals: the user ids of the people who may approve. Each of them also needs
titan:approval:decide(andtitan:approval:readto list requests).
Allow reads
allowInPolicy reads the policy, adds an allow rule, removes deny-all and saves the result with the next revision:
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:
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 option | Default | Meaning |
|---|---|---|
humanPrincipalIds | required | User ids of the people in the approval role. |
quorum | 1 | How many approvals complete a request, 1 to 8. |
maximumAgeSeconds | 3600 | How long a request may stay open, 60 to 604800 seconds. A request not tied to a durable session still ends within 24 hours. |
requesterSeparationRequired | true | The person who made the request can't approve it. |
delegatorSeparationRequired | false | The 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):
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 code | Why | What to do |
|---|---|---|
409 POLICY_REVISION_STALE | source_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_INVALID | The 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_UNSUPPORTED | A rule uses a limit or obligation Titan can't enforce yet. | Remove that term. |
400 OBLIGATION_PROFILE_UNKNOWN | A 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_RETIRED | The 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:
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.
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.jsonThe 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.