Implementing OAuth Scopes
The OAuth flow requires permission "scopes" which describe the level of access granted with the session. For now, granular permissions have been implemented on the bsky.social hosting service, and the self-hosted PDS distribution. Work on permission sets (including lexicon resolution) is in progress. Developers may start to implement more granular permissions -- for example, apps only asking for permissions to specific record types or API endpoints. We expect most apps to use the higher-level "permission sets" when they become available, which will provide more accessible language about the permissions being granted.
The minimal set of OAuth permissions that a third-party AT application should request to sign in with Bluesky are:
atproto
If you are making use of Bluesky profile information, you may also need:
rpc:app.bsky.actor.getProfile?aud=did:web:api.bsky.app#bsky_appview
If you need to link any uploaded images or videos to the records (posts) you create, you will also need:
blob:*/*
The ergonomics of OAuth scopes in Atproto are still evolving. This minimal set is designed to provide a known-good starting point for app developers that does not grant unnecessary permissions. While we finalize granular permission scopes, we are also supporting a set of temporary coarse-grained scopes called the "transition scopes". There are currently no plans to deprecate either the transition scopes or the use of App Passwords. For an overview of these transition scopes, and more in-depth information on OAuth, see Authorization Scopes. For the granular permission scopes, see Permissions.
Clients
OAuth client software is identified by a globally unique client_id. Distinct variants of client software may have distinct client_id values; for example the browser app and Android (mobile OS) variants of the same software might have different client_id values. The client_id must be a fully-qualified web URL from which the client-metadata JSON document can be fetched. For example, https://app.example.com/oauth-client-metadata.json. Some more about the client_id:
- it must be a well-formed URL, following the W3C URL specification
- the schema must be
https://, and there must not be a port number included. Note that there is a special exception forhttp://localhostclient_idvalues for development. - the path does not need to include
oauth-client-metadata.json, but it is helpful convention.
If you have been using client-metadata.json rather than oauth-client-metadata.json, you can make this change to have your domain display on the auth flow page, rather than a URL string.
The auth flow page will display all the relevent permissions being granted. This is true both for apps using granular permissions, and for those using the transitional OAuth scopes.
Client Apps should be sure to check which auth scopes were actually approved during the auth flow. In particular, when requesting permission to read an account email address (account:email), the user might decline that permission while granting others. In theory, any individual permission might be denied while the overall request is granted.