OAuth Scopes - Anghami + OSN+ SDK

Scopes are intentionally broad — three values, each covering a coherent capability area. Request only what you need.

Defined scopes

Scope	Enum	Grants
`read`	`AUTH_SCOPE_READ`	Catalog, search, browse, library, playlists, profile reads.
`stream`	`AUTH_SCOPE_STREAM`	Stream acquisition (`AcquireMusicStream`, `AcquireVideoStream`) — the billable event.

Defined in sdk/auth/v1/scope.proto. A write scope (value 2) is reserved in the enum range but not yet exposed — library and playlist mutations are not in the public SDK today. When mutations land, write will be the scope to request.

Requesting scopes

Pass a space-separated list in the OAuth authorization URL:

&scope=read+stream

The user sees the scopes during consent and can refuse. The granted scopes are echoed back in the token response — always check the actual scope field on the response, not the requested scopes, since the user may have granted a subset.

Per-RPC scope requirements

Service / RPC	Required
`MusicCatalogService.`, `VideoCatalogService.`	`read` (or API key)
`DiscoveryService.*`	`read` (or API key)
`SoundtrackService.*`	`read` (or API key)
`PlaylistService.GetPlaylist`	`read` (or API key — public playlists only with API key)
`PlaylistService.GetUserPlaylists`	`read`
`LibraryService.*`	`read`
`UserService.GetCurrentUser`	`read`
`StreamingService.AcquireMusicStream`	`stream`
`StreamingService.AcquireVideoStream`	`stream`
`DeveloperService.*`	OAuth (any scope) — gated by developer identity
`AuthService.*`	None (these are the auth endpoints)

Scope vs API key

Capability	API key	OAuth `read`	OAuth `stream`
Catalog reads	✅	✅	(irrelevant)
Library reads	❌	✅	(irrelevant)
Stream acquisition	❌	❌	✅

In short: API keys are for non-user catalog access. OAuth is for everything user-scoped, with stream separated out so users can grant catalog access without granting playback (and so you can audit billable acquires against tokens that were specifically authorized for it).

Best practices

Request narrow. If your app only browses the catalog, request read. Don’t ask for stream you won’t use.
Drop scopes on degraded flows. A read-only “preview mode” should drop stream from its scope request.
Re-authorize for new scopes. You cannot upgrade an existing token’s scopes — the user must re-authorize through /v1/auth/authorize with the new scope set.
Inspect what you got. Always check the response scope field; users can deselect scopes during consent.