Scopes determine which permissions a Developer API application wants from the signed-in member. Scopes do not override that member's permissions. To use a resource, the application must have the matching scope and the member must have the matching permission in that organization. More scopes are planned when the API version changes, so check back when the version changes.
The application may request these scopes:
read_organization
Allows the API application to read global information about the organizational structure. The approval screen can grant this when the member is an assignor, an observer, or an organization administrator in that organization.
add_to_organization
Allows the API application to add new and update existing information within the subscription. The approval screen can grant this when the member is an assignor or an organization administrator in that organization.
manage_organization
Allows the API application to perform just about every action on behalf of the subscription. The approval screen can grant this only when the member is an organization administrator in that organization.
read_personal_schedule
Allows the API application read-only access to the user's personal schedule and assignments. Any signed-in member can grant this.
manage_personal_schedule
Allows the API application to fully manage the user's personal schedule and assignments. Any signed-in member can grant this.
read_personal_account
Allows the API application read-only access to the user's personal account information and settings. Any signed-in member can grant this.
manage_personal_account
Allows the API application to fully manage the user's personal account information and settings. Any signed-in member can grant this.
These scopes match the Developer API documentation.
Who can grant organization scopes
Organization scopes are checked separately for each organization the member belongs to. Being an organization administrator in one organization does not grant write scopes in another. Belonging to a second organization is not a blocker by itself.
If none of the member's organizations can grant any requested scope, the approval page says: This developer wants permissions that you don't currently have. You won't be able to complete this, sorry. That message is about the member's role in the organizations being authorized. It is not a Free-plan limit. Developer API plans change daily and per-minute call limits only. See API Rate Limits & Pricing.
Schedule resources
Use the /schedule resources to work with events.
Listing or reading events needs read_organization, add_to_organization, or manage_organization.
Adding, updating, cancelling, or deleting events needs add_to_organization or manage_organization. Either scope is enough.
Cancel and delete use the schedule delete resource. Set the operation to cancel or delete. Cancelling keeps the event and notifies the people on it. Deleting removes an unpublished event permanently. Both are permanent.
More than one organization
The approval screen can list every organization the member belongs to that can grant at least one requested scope. The member can uncheck an organization, or uncheck individual scopes, before choosing Accept. There is no way to ask the requestCode resource to include only one organization. After Accept, each accepted organization receives its own authorization code. If more than one is issued, the codes are comma-separated. Use the code for the organization you want the later API calls to act on. See How do I get a Developer access token?
When a scope is missing or refused
API developers should build their applications to handle missing scopes or scopes the user refuses to provide. For example, an API application may request the scopes read_personal_account and manage_personal_account from the user via the oAuth2 resources. However, the user, during the authorization stage, may refuse to allow the manage_personal_account scope and only allow the read_personal_account scope. In this case, the API application should accommodate and adjust any future API calls for that user based on the scopes that the user actually provided.
As an additional example, the API application may request the manage_personal_account and the manage_organization scopes from the user. If the user has only General Member permissions and has no permissions on their account to manage their organization, they will be unable to provide the API application the manage_organization scope. Similar to above, the API application should appropriately handle this based on the scopes that are actually returned to the API application after the oAuth2 authorization stages.