zmb3/spotify: A Go Wrapper for Spotify Web API Authentication

What zmb3/spotify Covers

zmb3/spotify addresses the gap between Go's standard HTTP and OAuth2 packages and the resource-oriented surface of Spotify's Web API. The README describes it as a Go wrapper for working with the Spotify Web API and says it aims to support every task in Spotify's Web API Endpoint Reference. The repository layout supports that claim through separate files for albums, artists, audio analysis, audio features, categories, libraries, players, playlists, recommendations, searches, shows, tracks, users, cursors, pages, and request options.

The intended users are Go developers building services or command-line tools that need Spotify data or actions. Depending on the authentication flow, an application can use client credentials for public API access or authorization code flow for access involving a user's private data. The package does not provide a Spotify application interface. It provides a Go library that makes authenticated requests and represents Spotify resources as Go types.

The library also accounts for a practical Spotify constraint. The README states that all Web API endpoints require an access token and that the API throttles requests sent too rapidly. That makes authentication and request control part of the package's practical scope, rather than leaving every caller to build those pieces independently. The library's examples directory contains directories for authentication, command-line use, features, paging, player operations, profiles, recommendations, and search, which gives new users concrete areas from which to start.

Spotify OAuth2 and Token Flow

Authentication is centered on the package's `Authenticator` type. Spotify uses OAuth2, but the relevant flow depends on what the application needs. The README distinguishes client credentials flow from authorization code flow. Client credentials can provide an application token, but it does not authorize access to a user's private data. For most private-data use cases, the README directs developers to authorization code flow.

The documented flow starts by registering an application in the Spotify Developer Dashboard. The resulting client ID and secret can be supplied through `SPOTIFY_ID` and `SPOTIFY_SECRET`, or they can be passed manually. The redirect URL must exactly match a URL registered for the application. Scopes determine which permissions the user is prompted to authorize, and the example uses `spotifyauth.ScopeUserReadPrivate`.

The application calls `AuthURL(state)` to create the URL sent to the user. The `state` value identifies the session, so the callback handler must use the same value when requesting the token. After Spotify redirects back, `auth.Token(r.Context(), state, r)` exchanges the callback request for a token. `auth.Client(r.Context(), token)` then creates an HTTP client that carries the token, and `spotify.New(...)` creates the Spotify client used for authenticated requests.

This is a client-side application flow embedded in a Go handler. The README says that using the library means agreeing to Spotify's Developer Terms of Use. It also links to Spotify's authorization guide and Go's `golang.org/x/oauth2` documentation, which are the relevant external references for the underlying protocol.

First Installation and Authenticated Request

Install the package with the command documented in the README. The module path includes the major version suffix `/v2`, so the import and installation path should remain consistent with the repository's `go.mod` file.

go get github.com/zmb3/spotify/v2

After registering an application and configuring the redirect URL, the following is the README's authentication pattern. Set `SPOTIFY_ID` and `SPOTIFY_SECRET` before starting the application, then use the same `state` value for the authorization URL and callback handler.

auth := spotifyauth.New(spotifyauth.WithRedirectURL(redirectURL), spotifyauth.WithScopes(spotifyauth.ScopeUserReadPrivate))
url := auth.AuthURL(state)

The callback exchanges the incoming request for a token and creates the Spotify client. The actual HTTP route and the code that sends the user to `url` are application responsibilities. The README does not prescribe a server framework or a fixed route.

token, err := auth.Token(r.Context(), state, r)
if err != nil {
  http.Error(w, "Couldn't get token", http.StatusNotFound)
  return
}
client := spotify.New(auth.Client(r.Context(), token))

At this point, `client` is ready for authenticated requests. The examples directory contains separate examples for search, player actions, paging, profiles, recommendations, features, and command-line use, so the first request should be selected from the area your application actually needs.

Typed Spotify Resources and Paging

The repository organizes the Web API by resource rather than by a single generic request function. Files such as `album.go`, `artist.go`, `playlist.go`, `search.go`, and `track.go` indicate that callers work with domain-specific Go values. This is more useful than manually decoding every Spotify JSON response at each call site, although the exact method names and field behavior are not documented in the README excerpt.

Spotify responses can be paginated. The repository includes `page.go`, `cursor.go`, and tests for paging, while the README points to the `examples/paging` directory. That indicates that cursor or page handling is part of the package's model. Developers should account for multiple pages when a search result, playlist, or user collection is larger than one response. The README does not state whether all endpoint variants expose the same paging abstraction, so that should be checked against the relevant source file before designing application state.

The examples are particularly important for determining the supported call shape. `examples/search`, `examples/player`, and `examples/recommendation` cover different API areas. A direct HTTP wrapper still leaves application decisions such as which fields to persist, how to represent partial responses, and how to handle an empty result. The library reduces JSON handling, but it does not remove those domain decisions.

Rate Limits, Retries, and Missing Market Data

The package includes an opt-in retry mechanism for Spotify throttling. The README states that the API can throttle requests when they are sent too rapidly and instructs users to pass `WithRetry(true)` to `New`. Enabling that option tells the client to wait and re-attempt a request according to its configured behavior. It is useful for applications that make bursts of calls, but it also changes failure timing and should be selected deliberately.

A second documented edge case concerns missing market information. The README says Spotify commonly returns `null` for details about a track or episode when no market information is available for the request. This often happens with an application token that is not impersonating a user. With a user-associated token, Spotify may use the user's market from the profile when producing the response.

That means a response that looks incomplete in one authentication context may not be incomplete in another. Code should not assume that every nullable field is a transport failure. The library can return the API's missing values, but the application must decide whether to omit them, display a fallback, request another authorization context, or treat the absence as a meaningful product condition. The README does not document a library-wide fallback for market data.

Maintenance, Compatibility, and License

The repository is not archived. Its last push was on 2026-07-02, which is more recent than the latest listed release. The release history includes `v2.4.3` on 2024-11-11, `v2.4.2` on 2024-04-19, and `v2.4.1` on 2024-01-22. These dates show that releases and repository activity are separate signals: the most recent push is newer than the newest published release listed here.

The module declares Go 1.16 in `go.mod` and depends on `golang.org/x/oauth2`, with several indirect dependencies including `golang.org/x/net` and `google.golang.org/protobuf`. Consumers should review those dependency versions during upgrades, especially when their own Go version differs from the module's declared baseline. The repository also contains tests for major resource files, which provides evidence that the package is organized around tested API areas, but the README does not claim compatibility with every Spotify Web API change.

The project uses the Apache-2.0 license. That permits use under the license's terms and includes the associated notices and conditions. It does not replace compliance with Spotify's Developer Terms of Use, which the README says users agree to by using the library. The license and Spotify's service terms are separate obligations, and the library does not remove the need to review them.

When a Direct Spotify Web API Client Is the Wrong Choice

zmb3/spotify is not a complete Spotify player. The repository includes player-related code, but the README describes a Web API wrapper rather than audio decoding, playback control outside Spotify, or a polished desktop experience. An application that needs local media playback, offline storage, or a user interface will still need separate components.

It is also not an administrative dashboard for Spotify application management. Registration, redirect URL configuration, client credentials, and consent screens remain tied to Spotify's developer platform. The library does not document a way to bypass OAuth2 or obtain private user data without the appropriate user authorization. Application developers must protect the client secret and token handling according to their deployment model and Spotify's requirements.

Compared with calling Spotify's HTTP endpoints directly, zmb3/spotify offers Go-oriented resource types, authentication helpers, paging-related code, and an optional retry option. Compared with a full Spotify integration platform, it is narrower and leaves storage, caching, observability, policy enforcement, and deployment concerns to the application. The choice is therefore most defensible for a Go service with direct Spotify API requirements, not for a general-purpose music application built only around catalog search.

Editorial conclusion

Adopt zmb3/spotify for a Go service that directly integrates with Spotify Web API resources and can manage OAuth2 redirects, scopes, tokens, and Spotify rate limits. Do not choose it as a standalone Spotify client, a complete user-interface layer, or a replacement for Spotify's server-side authorization model. Verify first that your Spotify application configuration, redirect URL, requested scopes, user market context, and Go dependency versions match the API behavior your service expects.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. zmb3/spotify on GitHub