Scope Grants

Scope grants define what an agent is authorized to do under a credential. They follow the OAuth 2.1 Rich Authorization Requests (RFC 9396) shape: structured authorization objects with a type field and optional type-specific constraints. A credential may carry multiple scope grants. A tool invocation is authorized if it satisfies any scope grant. Each grant is satisfied only if all its constraints are met. The supported grant types are published in the discovery document as authorization_details_types_supported:

Type	Description
`hasp.data.read`	Read records from an app, optionally narrowed to specific entities, fields, and filters.
`hasp.data.write`	Write records to an app, optionally narrowed to specific entities and fields.
`external.tool.invoke`	Invoke one named external tool. One grant per tool.
`tool.destructive`	Invoke one named destructive capability. Wildcards are rejected — the tool must be named.
`agent.delegate`	Delegate authority to another agent, bounded by `max_chain_depth` (1–10).
`agent.compose`	Compose with another agent by `agent_id`.
`human.escalate`	Escalate to a human — exactly one of `to_role` or `to_user_id`.
`workflow.schedule`	Create scheduled runs for named workflows, bounded by horizon, interval, live-schedule count, and depth.
`workflow.invoke`	Invoke named workflows over A2A. The wildcard `*` is permitted only as the sole element.

Scope type reference

`hasp.data.read`

Authorize the agent to read records from the HASP Data API.

{
  "type": "hasp.data.read",
  "app_id": "app_01ARZ3...",
  "entities": ["patient_intake", "patient_profile"],
  "filters": {
    "patient.assigned_clinician_id": "{{delegating_user.id}}"
  }
}

Field	Description
`app_id`	Restrict to a specific app’s data. Omit to allow reads across all apps.
`entities`	Restrict to specific entity types. Omit to allow all readable entities.
`filters`	Field-level filters applied to every read. Supports substitution syntax.

`hasp.data.write`

Authorize the agent to create or update records in the HASP Data API.

{
  "type": "hasp.data.write",
  "app_id": "app_01ARZ3...",
  "entities": ["scheduling_request"],
  "fields": ["requested_specialty", "requested_window", "notes"]
}

Field	Description
`app_id`	Restrict to a specific app.
`entities`	Restrict to specific entity types.
`fields`	Restrict to specific writable fields. The agent cannot write fields not in this list.

hasp.data.read does not implicitly grant hasp.data.write. A separate grant is required for write access even on the same entities.

`external.tool.invoke`

Authorize the agent to call an external or registered tool.

{
  "type": "external.tool.invoke",
  "tool_id": "calendar.find_slots",
  "rate_limit": 60,
  "constraints": {
    "from_address": ["[email protected]"],
    "templates_only": true
  }
}

Field	Description
`tool_id`	The registered tool identifier. Required.
`rate_limit`	Optional rate limit: maximum invocations per hour (integer). Omit for no rate limit.
`constraints`	Arbitrary key-value constraints enforced at invocation time. Keys and values are tool-specific.

Each external.tool.invoke grant applies to a single tool. To authorize multiple tools, add one grant per tool.

`agent.delegate`

Authorize the agent to issue a child credential to another registered agent.

{
  "type": "agent.delegate",
  "to_agent_id": "agent_followup_01J...",
  "max_chain_depth": 1
}

Field	Description
`to_agent_id`	The agent this credential may delegate to. Required.
`max_chain_depth`	Required. Maximum additional delegation depth from the child, an integer from 1 to 10. `1` means the child cannot further delegate. Exceeding it fails with `AGENT_DELEGATION_CHAIN_DEPTH_EXCEEDED`.

The child credential’s scopes are bounded by the parent’s. An agent cannot delegate scopes it does not itself hold.

`human.escalate`

Authorize the agent to escalate to a human via a configured channel.

{
  "type": "human.escalate",
  "to_role": "on_call_clinician",
  "channels": ["pager", "in_app"]
}

Field	Description
`to_role`	Org role to escalate to.
`to_user_id`	A specific user to escalate to.
`channels`	Required, non-empty. Delivery channels for the escalation.

Supply exactly one of to_role or to_user_id. Sending neither, or both, is rejected at issuance.

`tool.destructive`

Authorize the agent to invoke a single named destructive capability — one whose effects cannot be undone by a subsequent call.

{
  "type": "tool.destructive",
  "tool_id": "records.purge"
}

Field	Description
`tool_id`	Required. The specific destructive capability.

A wildcard tool_id of "*" is rejected: a destructive capability must be named explicitly. Grant one per capability.

`agent.compose`

Authorize the agent to compose with another registered agent.

{
  "type": "agent.compose",
  "agent_id": "agent_summarizer_01J..."
}

Field	Description
`agent_id`	Required. The agent this credential may compose with.

`workflow.invoke`

Authorize the agent to invoke named workflows over A2A.

{
  "type": "workflow.invoke",
  "workflow_ids": ["wf_care_coordination_01J..."]
}

Field	Description
`workflow_ids`	Required, non-empty. The workflows this credential may invoke. The wildcard `"*"` is permitted only as the sole element.

The A2A route requires the workflow.run capability, which this grant confers. A credential whose grant names specific workflows is rejected when it invokes any other workflow, even one that is agent-callable in the same org.

`workflow.schedule`

Authorize the agent to create scheduled runs of named workflows.

{
  "type": "workflow.schedule",
  "workflow_ids": ["wf_intake_01J..."],
  "max_horizon": "P30D",
  "min_interval": "PT1H",
  "max_live_schedules": 20,
  "max_schedule_depth": 0
}

Field	Description
`workflow_ids`	Required, non-empty. The workflows that may be scheduled. The wildcard `"*"` is permitted only as the sole element, and requires an org-policy opt-in.
`max_horizon`	Required. ISO 8601 duration — how far ahead a run may be scheduled (e.g. `P30D`).
`min_interval`	Required. ISO 8601 duration — the shortest permitted gap between runs (e.g. `PT1H`).
`max_live_schedules`	Required. Non-negative integer cap on concurrently live schedules.
`max_schedule_depth`	Required. Non-negative integer — how deep a scheduled run may itself schedule further runs.

Tier ceilings apply on top of the grant; the effective bound is the tighter of the two.

Substitution syntax

Filters and constraints may use substitution syntax to bind values at credential issuance time:

Variable	Resolves to
`{{delegating_user.id}}`	The ULID of the user who authorized the credential
`{{delegating_user.email}}`	The email of the delegating user
`{{org.id}}`	The org’s ULID
`{{org.slug}}`	The org’s slug
`{{current_time}}`	ISO 8601 timestamp at issuance

Substitution happens at credential issuance, not at invocation. The credential carries already-resolved values. This makes scope fully auditable — the agent cannot re-evaluate bindings at runtime. Example:

{
  "type": "hasp.data.read",
  "filters": {
    "patient.assigned_clinician_id": "{{delegating_user.id}}"
  }
}

Issued as:

{
  "type": "hasp.data.read",
  "filters": {
    "patient.assigned_clinician_id": "01JQUSER0000000000000000"
  }
}

Allowed scope types

Each agent definition has an allowed_scope_types list. A credential cannot be issued with a scope type that is not in the agent’s allowed types. To configure which scope types an agent may receive:

Dashboard: Developers → Agents → [agent name] → Settings
API: PATCH /v1/agents/{agent_id} with allowed_scope_types

Setting allowed_scope_types to null permits all scope types. This is the default for newly registered agents.

Scope type restrictions

Scope types are an enumerated set — new types require a platform update. Customers cannot define custom scope types. This is intentional: a scope type the platform does not recognize cannot be enforced or audited, which breaks the regulated-industry trust model. The current scope type set is:

hasp.data.read
hasp.data.write
external.tool.invoke
agent.delegate
human.escalate

AI Studio

Platform

AI API

App Builder SDK

Scope Grants

Scope type reference

`hasp.data.read`

`hasp.data.write`

`external.tool.invoke`

`agent.delegate`

`human.escalate`

`tool.destructive`

`agent.compose`

`workflow.invoke`

`workflow.schedule`

Substitution syntax

Allowed scope types

Scope type restrictions

​Scope type reference

​hasp.data.read

​hasp.data.write

​external.tool.invoke

​agent.delegate

​human.escalate

​tool.destructive

​agent.compose

​workflow.invoke

​workflow.schedule

​Substitution syntax

​Allowed scope types

​Scope type restrictions

Scope type reference

`hasp.data.read`

`hasp.data.write`

`external.tool.invoke`

`agent.delegate`

`human.escalate`

`tool.destructive`

`agent.compose`

`workflow.invoke`

`workflow.schedule`

Substitution syntax

Allowed scope types

Scope type restrictions