Skip to main content
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.

​
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}}"
  }
}
FieldDescription
app_idRestrict to a specific app’s data. Omit to allow reads across all apps.
entitiesRestrict to specific entity types. Omit to allow all readable entities.
filtersField-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"]
}
FieldDescription
app_idRestrict to a specific app.
entitiesRestrict to specific entity types.
fieldsRestrict 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
  }
}
FieldDescription
tool_idThe registered tool identifier. Required.
rate_limitOptional rate limit: maximum invocations per hour (integer). Omit for no rate limit.
constraintsArbitrary 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
}
FieldDescription
to_agent_idThe agent this credential may delegate to. Required.
max_chain_depthMaximum additional delegation depth from the child. 1 means the child cannot further delegate. Max 3.
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"]
}
FieldDescription
to_roleOrg role to escalate to. Omit to allow escalation to any configured role.
channelsDelivery channels. Omit to allow all configured channels.

​
Substitution syntax

Filters and constraints may use substitution syntax to bind values at credential issuance time:
VariableResolves 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