Sub-issue of highflame-ai/highflame-sdk#143 — the scope-mechanism review.
The contradiction
The same field carries opposite guidance on two live endpoints.
POST /identities — internal/handler/identity.go:
AllowedScopes []string `json:"allowed_scopes,omitempty" doc:"Deprecated: set scope ceiling on the identity's credential policy"`
POST /agents/register — internal/handler/agent.go:
AllowedScopes []string `json:"allowed_scopes,omitempty" doc:"OAuth scopes this identity may request. Required for token_exchange since the exchange only grants scopes in the intersection of the subject's granted scopes and the actor's allowed_scopes."`
One says deprecated. The other says required. internal/service/agent.go sides with the first:
AllowedScopes []string // Deprecated: set scope ceiling on the identity's credential policy.
Why it matters
agents.register is the endpoint people actually use, and it is the one that does not say deprecated. Every downstream document follows it — the SDK's agents.register(allowed_scopes=...), both READMEs, the quickstart notebook, and the integration fixtures all teach the field as the way to set an agent's ceiling.
If it really is deprecated, all of that teaches a path that is scheduled to disappear, and there is no migration note anywhere.
The runtime keeps it working: effectiveAllowedScopes prefers policy.AllowedScopes and falls back to identity.AllowedScopes only when the policy sets no scope restriction. So the field is a fallback, not a synonym — a credential policy also carries max TTL, allowed grant types, required trust level, required attestation, and max delegation depth.
Ask
Settle it, then make the surface consistent:
- If deprecated — mark it so on
POST /agents/register too, give agents.register a first-class way to attach or create a scope-bearing policy, and open an SDK issue to migrate the docs and fixtures.
- If supported — drop the deprecation note from
POST /identities and RegisterAgentRequest, and document the precedence rule explicitly: the policy wins, the field is the fallback.
Either way, one answer on every endpoint.
Related
Interacts with the default-policy decision (sibling issue). If the default policy grows a scope ceiling, the fallback stops being reachable for default-policy identities, which changes the answer here.
Sub-issue of highflame-ai/highflame-sdk#143 — the scope-mechanism review.
The contradiction
The same field carries opposite guidance on two live endpoints.
POST /identities—internal/handler/identity.go:POST /agents/register—internal/handler/agent.go:One says deprecated. The other says required.
internal/service/agent.gosides with the first:Why it matters
agents.registeris the endpoint people actually use, and it is the one that does not say deprecated. Every downstream document follows it — the SDK'sagents.register(allowed_scopes=...), both READMEs, the quickstart notebook, and the integration fixtures all teach the field as the way to set an agent's ceiling.If it really is deprecated, all of that teaches a path that is scheduled to disappear, and there is no migration note anywhere.
The runtime keeps it working:
effectiveAllowedScopespreferspolicy.AllowedScopesand falls back toidentity.AllowedScopesonly when the policy sets no scope restriction. So the field is a fallback, not a synonym — a credential policy also carries max TTL, allowed grant types, required trust level, required attestation, and max delegation depth.Ask
Settle it, then make the surface consistent:
POST /agents/registertoo, giveagents.registera first-class way to attach or create a scope-bearing policy, and open an SDK issue to migrate the docs and fixtures.POST /identitiesandRegisterAgentRequest, and document the precedence rule explicitly: the policy wins, the field is the fallback.Either way, one answer on every endpoint.
Related
Interacts with the default-policy decision (sibling issue). If the default policy grows a scope ceiling, the fallback stops being reachable for default-policy identities, which changes the answer here.