mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
Mintlify Agent
65fd3621dc
- Created 111 MDX documentation files - Added 89 API endpoint pages across 14 categories - Included 11 concept guides and 7 tutorials - Configured Mintlify with Spotify branding (#1DB954) - All pages validated successfully
154 lines
3.6 KiB
Plaintext
154 lines
3.6 KiB
Plaintext
---
|
|
title: "Scopes"
|
|
description: "Understanding authorization scopes in the Spotify Web API"
|
|
---
|
|
|
|
# Scopes
|
|
|
|
Authorization scopes define the level of access your application has to a user's Spotify data. When requesting authorization, you must specify which scopes your app needs.
|
|
|
|
## Available scopes
|
|
|
|
### Images
|
|
|
|
<ParamField scope="ugc-image-upload">
|
|
Upload images to Spotify (for playlist covers)
|
|
</ParamField>
|
|
|
|
### Playlists
|
|
|
|
<ParamField scope="playlist-read-private">
|
|
Read access to user's private playlists
|
|
</ParamField>
|
|
|
|
<ParamField scope="playlist-read-collaborative">
|
|
Read access to collaborative playlists
|
|
</ParamField>
|
|
|
|
<ParamField scope="playlist-modify-public">
|
|
Write access to user's public playlists
|
|
</ParamField>
|
|
|
|
<ParamField scope="playlist-modify-private">
|
|
Write access to user's private playlists
|
|
</ParamField>
|
|
|
|
### Playback
|
|
|
|
<ParamField scope="user-read-playback-state">
|
|
Read access to playback state
|
|
</ParamField>
|
|
|
|
<ParamField scope="user-modify-playback-state">
|
|
Control playback (play, pause, skip, etc.)
|
|
</ParamField>
|
|
|
|
<ParamField scope="user-read-currently-playing">
|
|
Read currently playing track
|
|
</ParamField>
|
|
|
|
### Listening history
|
|
|
|
<ParamField scope="user-read-recently-played">
|
|
Read recently played tracks
|
|
</ParamField>
|
|
|
|
<ParamField scope="user-top-read">
|
|
Read user's top artists and tracks
|
|
</ParamField>
|
|
|
|
### Library
|
|
|
|
<ParamField scope="user-library-read">
|
|
Read saved tracks, albums, and shows
|
|
</ParamField>
|
|
|
|
<ParamField scope="user-library-modify">
|
|
Save and remove tracks, albums, and shows
|
|
</ParamField>
|
|
|
|
### Users
|
|
|
|
<ParamField scope="user-read-email">
|
|
Read user's email address
|
|
</ParamField>
|
|
|
|
<ParamField scope="user-read-private">
|
|
Read user's subscription details (premium status)
|
|
</ParamField>
|
|
|
|
### Follow
|
|
|
|
<ParamField scope="user-follow-read">
|
|
Read following state of artists and users
|
|
</ParamField>
|
|
|
|
<ParamField scope="user-follow-modify">
|
|
Follow and unfollow artists and users
|
|
</ParamField>
|
|
|
|
### Streaming
|
|
|
|
<ParamField scope="streaming">
|
|
Control playback via Web Playback SDK
|
|
</ParamField>
|
|
|
|
<ParamField scope="app-remote-control">
|
|
Control playback via app remote SDK
|
|
</ParamField>
|
|
|
|
## Requesting scopes
|
|
|
|
Specify scopes as a space-separated string in authorization requests:
|
|
|
|
```javascript
|
|
const scopes = [
|
|
'user-read-private',
|
|
'user-read-email',
|
|
'playlist-read-private',
|
|
'playlist-modify-public'
|
|
].join(' ');
|
|
|
|
const authUrl = `https://accounts.spotify.com/authorize?` +
|
|
`client_id=${clientId}&` +
|
|
`response_type=code&` +
|
|
`redirect_uri=${redirectUri}&` +
|
|
`scope=${encodeURIComponent(scopes)}`;
|
|
```
|
|
|
|
## Best practices
|
|
|
|
<AccordionGroup>
|
|
<Accordion title="Request minimum scopes">
|
|
Only request scopes your app actually needs. Users are more likely to approve minimal permissions.
|
|
</Accordion>
|
|
<Accordion title="Explain why you need access">
|
|
Clearly communicate why your app needs specific permissions.
|
|
</Accordion>
|
|
<Accordion title="Request additional scopes later">
|
|
If you need more permissions later, request them only when needed rather than all upfront.
|
|
</Accordion>
|
|
<Accordion title="Handle denied scopes gracefully">
|
|
Your app should handle cases where users deny specific permissions.
|
|
</Accordion>
|
|
</AccordionGroup>
|
|
|
|
## Scope validation
|
|
|
|
After authorization, check which scopes were actually granted:
|
|
|
|
```javascript
|
|
const tokenResponse = await getAccessToken(code);
|
|
const grantedScopes = tokenResponse.scope.split(' ');
|
|
|
|
if (!grantedScopes.includes('playlist-modify-public')) {
|
|
// User didn't grant playlist modification permission
|
|
// Disable that feature or prompt again
|
|
}
|
|
```
|
|
|
|
<Note>
|
|
The access token includes information about granted scopes. Always validate you received the scopes you need.
|
|
</Note>
|
|
|