This document formally defines the token scope specification for Sourcegraph Accounts Management System (SAMS) :

1. Components of a token scope, i.e. how do token scopes look?
2. Token scope matching strategy, i.e. how authorization works?

These scopes are used for user access tokens, as well as SAMS M2M (machine-to-machine) authentication and authorization.

Basic format

A scope is always consists of three parts: service, permission hierarchy, and action, and are separated by double colons ::, e.g. sams::user.roles::read, ssc::subscriptions::read:

1. The total length of a scope cannot exceed 255 characters.
2. Service: the slug of the service name, up to 30 characters.
   • It can only contain [a-z_] characters, e.g. sams, ssc, dotcom, cody_gateway.
3. Permission hierarchy: the hierarchy of the permissions under the given service, up to 215 characters.
   • It can only contain [a-z_.] characters, e.g. user, user.metadata, user.roles.
   • There is no conceptual limit for the number of hierarchy levels (other than the scope length limit).
   • Every hierarchy grants access to all sub-permissions (aka. prefix matching), e.g.:
     • user grants user.roles, user.metadata, etc.
     • user.metadata grants user.metadata.cody, user.metadata.dotcom, etc.
     • If an access token is granted with <service>::user.profile::write, the client is able to write to ALL aspects of the user profile. If a service wants to only allow access to a specific section, the service will need to create more specialized scopes. e.g. granting both <service>:user.profile.avatar_url::write and <service>::user.profile.display_name::write.
   • The hierarchy design also helps us to avoid unnecessarily updating all services when a new sub-permission is introduced.
   • It is by design that “access-to-everything” of a service is explicitly disallowed, therefore no notion provided for it.
4. Action: the allowed action for the given permission of the given service, up to 10 characters.
   • It is a predefined/hardcoded list of values, it has no point being dynamic (strings) for being conservative:
     • read: allowed to read resources from the service
     • write: allowed to create or make updates to the resources of the service
     • delete: allowed to delete resources on the service
   • Every (permission, action) must be granted explicitly, there is no action hierarchy, e.g. having write permission doesn’t automatically grant read permission.

Scope alias

This is initially intended for making OIDC scopes be compatible with our design (profile -> sams::user.profile::read), but could also be a useful extension in the future, e.g. in the event of scope renaming efforts.

How to add new token scopes

1. Add desired scopes to the sourcegraph/sourcegraph-accounts-sdk-go repository, e.g. https://github.com/sourcegraph/sourcegraph-accounts-sdk-go/pull/94.
2. Once merged, update the sourcegraph/sourcegraph-accounts repository to pull the SDK version that has your newly added scopes, e.g. https://github.com/sourcegraph/sourcegraph-accounts/pull/387.
   • To obtain correct version of the sourcegraph-accounts-sdk-go you can pull the most recent main of sourcegraph-accounts-sdk-go and run the following command: go list -m [github.com/sourcegraph/sourcegraph-accounts-sdk-go@main](<http://github.com/sourcegraph/sourcegraph-accounts-sdk-go@main>) The output should be something like: [github.com/sourcegraph/sourcegraph-accounts-sdk-go](<http://github.com/sourcegraph/sourcegraph-accounts-sdk-go>) v0.0.0-20250717161013-504cc426e4a6 which is a virtual version which needs to be put in the go.mod of sourcegraph-accounts repository.
3. Once merged, make sure a new SAMS deployment that has the new scopes is rolled out your desired environment (SAMS-dev and/or SAMS-prod) before deploying your service that requires these new scopes. Otherwise, authentication failure will occur due to missing required scopes.

References

• SAMS token scope specification draft