Derived Scope Not Assignable
URI: https://docs.ankatech.co/errors/derived-scope-not-assignable
HTTP Status: 422 Unprocessable Entity
When you see this
A role assignment of a Cryptographic Actor (POST /api/v3/admin/tenants/{tenantId}/actors/{actorId}/roles, operation assignActorRoles) submitted a scope the actor holds only because one of its capability grants is effective right now.
An actor's effective scopes are its direct role assignments plus the scopes derived from its effective capability grants. The role list (listActorRoles) returns that effective set, but the assignment writes direct assignments only, and it replaces them. A grant-derived scope is not an assignment: writing it as one would turn an authorization meant to end with its grant into a permanent one, so it is refused rather than silently dropped.
extensions.derivedScopes lists every refused name, in lexicographic order, and the detail names them too. A scope the actor holds both directly and through a grant is never refused: its assignment is real and may be replaced.
The check runs after the role names are validated, the actor is found and the actor is confirmed not to be owned by an internal crypto use case. Nothing was changed.
Common Causes
- A client read the actor's roles with
listActorRoles, changed one entry, and posted the whole list back, grant-derived scopes included. This is the common case: the console, the Admin SDK and any script following that read-modify-write shape reach it. - A list of scopes copied from another actor whose grants differ.
Response Example
{
"type": "https://docs.ankatech.co/errors/derived-scope-not-assignable",
"title": "Derived Scope Not Assignable",
"status": 422,
"detail": "These scopes are conferred by an effective capability grant and are not role assignments, so they cannot be submitted as one: [secure.encrypt, stream.encryptStream]. They are already in effect for this actor and will end when the grant does. Post the directly assigned scopes only.",
"instance": "/api/v3/admin/tenants/8b2e4f17-3c9a-4d61-a5f0-7e1b9c3d2a46/actors/3f2a1b4c-5d6e-7f80-9a1b-2c3d4e5f6071/roles",
"timestamp": 1763112600,
"extensions": {
"derivedScopes": ["secure.encrypt", "stream.encryptStream"],
"requestId": "9f4c1d8a-3b62-4e07-95a1-c8d02f6b17e5"
}
}
Content-Type: application/problem+json — the response follows RFC 9457 Problem Details.
How to Resolve
- Remove every name in
extensions.derivedScopesfrom the list and submit it again. Those scopes stay in force for as long as their grant is effective. - To withdraw a grant-derived scope, act on its source: revoke the capability grant (
revokeCapabilityGrant), or suspend or revoke the Cryptographic Exchange that owns it (suspendExchange,revokeExchange). A role write never removes it.
For full schema definitions, examples, and interactive testing, see the Developer Hub Reference.