We’ve rolled out a change to how API token scopes work on app.speckle.systems. Scope names have moved from the old two-part form (streams:read) to a three-part one (project.core.read), and the API now returns the new names.
Your existing tokens, apps and integrations keep working, and the old names are still accepted — but they are now deprecated and will be removed in a future release. There’s nothing you need to change today. There is something you’ll want to plan for.
Why
The old scopes were coarse. streams:read was a single string that, in practice, governed a dozen different things — reading projects, versions, saved views, webhook configuration, and more. There was no way to grant some of those and not others, and no way to tell from a token what it could actually do.
The new names describe one capability each, in the form domain.feature.verb:
project.core.read
project.version.read
project.savedView.read
workspace.blob.read
That means tokens can be scoped to what an integration actually needs, rather than to a broad bucket that happens to contain it.
What you’ll notice
Scope names you read back differ from the ones you sent. If you create a token with streams:read and then read that token’s scopes, you’ll get back the ~14 capabilities that scope has always granted — not streams:read itself. The same applies to app scopes.
This is not a permissions increase. The token can do exactly what it could before; the API is now describing that precisely instead of with one broad label. A list going from 3 entries to 30 is the same access, spelled out.
If you only ever send scope names, none of this affects you yet. If you read them — comparing, counting, storing, or displaying them — that’s where you’ll see the difference.
Reading the catalog
The full list of scopes a server offers, with a description for each, comes from the API:
query {
serverInfo {
scopes {
name
description
}
}
}
This is the authoritative list, and it’s server-specific — a deployment with certain modules disabled offers fewer. Read it at runtime rather than hard-coding a list. That’s good practice generally, and particularly worthwhile right now (see below).
The old names are deprecated
We intend to stop accepting streams:read and friends eventually. No removal date has been set - but treat them as on the way out rather than as a permanent alias.
This is still in progress
We’re partway through a larger permissions overhaul, and the specific scope names are not final. Some may be renamed, split, or narrowed over the coming weeks as we refine the model. The old names keep working throughout that period, so nothing breaks while we settle it — but if you adopt the new ones now, expect some churn.