Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Spotify

Scalekit connector
Open markdown

The Spotify connector lets your AI agent act in each user's Spotify account. Each user signs in to Spotify once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 47 tools.

Tools
47
What they doRead · write · destructive
30 · 15 · 230 read15 write2 destructive
Users sign in with
OAuth app
Your own Spotify app

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv
  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>
  3. Create the Spotify connection

    In AgentKit > Connections, create a Spotify connection and copy its redirect URI. The name you give it is the connection_name your code passes. See Configure connections.

  4. Register an OAuth app

    Spotify connections use your own OAuth app. Register one with Spotify and add the redirect URI you copied.

    Then enter the app's Client ID and Client Secret on the Spotify connection.

    Console steps with screenshots

    Create a Spotify app so Scalekit can authorize access to your users’ Spotify accounts. You’ll register the Scalekit redirect URI in the app, then add the app’s Client ID and Client secret to your Scalekit connection.

    1. Create a Spotify app

    2. Copy the redirect URI from Scalekit

      • In the Scalekit dashboard, go to AgentKit > Connections > Create Connection. Find Spotify and click Create.
      • Click Use your own credentials and copy the redirect URI. It looks like https://<SCALEKIT_ENVIRONMENT_URL>/sso/v1/oauth/<CONNECTION_ID>/callback.
    3. Add the redirect URI to your Spotify app

      • In your Spotify app, open Settings.

      • Under Redirect URIs, paste the Scalekit redirect URI, click Add, and then Save.

        Spotify app settings with the Scalekit redirect URI listed under Redirect URIs

    4. Copy your Client ID and Client secret

      • On the same Basic Information page, copy the Client ID.

      • Click View client secret and copy the Client secret.

        Spotify Basic Information page with the Client ID and the View client secret link

    5. Add the credentials in Scalekit

      • Return to your Spotify connection in Scalekit.
      • Enter the Client ID and Client secret, select the scopes your tools need, and click Save.
  5. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    const scalekit = new ScalekitClient(
    process.env.SCALEKIT_ENVIRONMENT_URL,
    process.env.SCALEKIT_CLIENT_ID,
    process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    const connector = 'spotify'
    const identifier = 'user_123'
    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Spotify:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    // Make your first call
    const result = await actions.executeTool({
    connector,
    identifier,
    toolName: 'spotify_devices_get',
    toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user signs in once. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • spotify_album_getGet Spotify catalog information for a single album by its Spotify ID.Read-only

    Get Album

    Get Spotify catalog information for a single album by its Spotify ID.

    Inputs

    idstringrequired
    The Spotify ID of the album
    marketstring
    ISO 3166-1 alpha-2 country code for market filtering

    Also accepts schema_version and tool_version to pin a version.

  • spotify_album_tracks_getGet Spotify catalog information about an album's tracks.Read-only

    Get Album Tracks

    Get Spotify catalog information about an album's tracks. Returns paginated list of simplified track objects.

    Inputs

    idstringrequired
    The Spotify ID of the album
    limitinteger
    Maximum number of tracks to return (default 20, max 50)
    marketstring
    ISO 3166-1 alpha-2 country code
    offsetinteger
    Index of the first track to return (default 0)

    Also accepts schema_version and tool_version to pin a version.

  • spotify_artist_albums_getGet Spotify catalog information about an artist's albums.Read-only

    Get Artist's Albums

    Get Spotify catalog information about an artist's albums. Optionally filter by album group.

    Inputs

    idstringrequired
    The Spotify ID of the artist
    include_groupsstring
    Comma-separated list of album types to include: album, single, appears_on, compilation
    limitinteger
    Maximum number of items to return (default 20, max 50)
    marketstring
    ISO 3166-1 alpha-2 country code
    offsetinteger
    Index of the first item to return (default 0)

    Also accepts schema_version and tool_version to pin a version.

  • spotify_artist_getGet Spotify catalog information for a single artist by their Spotify ID.Read-only

    Get Artist

    Get Spotify catalog information for a single artist by their Spotify ID.

    Inputs

    idstringrequired
    The Spotify ID of the artist

    Also accepts schema_version and tool_version to pin a version.

  • spotify_audiobook_chapters_getGet Spotify catalog information for an audiobook's chapters.Read-only

    Get Audiobook Chapters

    Get Spotify catalog information for an audiobook's chapters. Requires a valid Spotify ID for the audiobook.

    Inputs

    idstringrequired
    The Spotify ID of the audiobook
    limitinteger
    Maximum number of chapters to return (default 20, max 50)
    marketstring
    ISO 3166-1 alpha-2 country code
    offsetinteger
    Index of the first chapter to return for pagination

    Also accepts schema_version and tool_version to pin a version.

  • spotify_audiobook_getGet Spotify catalog information for a single audiobook.Read-only

    Get Audiobook

    Get Spotify catalog information for a single audiobook. Only available for markets where audiobooks are available.

    Inputs

    idstringrequired
    The Spotify ID of the audiobook
    marketstring
    ISO 3166-1 alpha-2 country code

    Also accepts schema_version and tool_version to pin a version.

  • spotify_chapter_getGet Spotify catalog information for a single audiobook chapter by its Spotify ID.Read-only

    Get Chapter

    Get Spotify catalog information for a single audiobook chapter by its Spotify ID.

    Inputs

    idstringrequired
    The Spotify ID of the chapter
    marketstring
    ISO 3166-1 alpha-2 country code

    Also accepts schema_version and tool_version to pin a version.

  • spotify_devices_getGet information about a user's available playback devices.Read-only

    Get Available Devices

    Get information about a user's available playback devices. Returns device IDs, names, types, and active status. Requires user-read-playback-state scope.

    Inputs

    This tool takes no inputs.

    Also accepts schema_version and tool_version to pin a version.