Recoup

Get started with Recoup.

Try Our Platform

Use Recoup’s AI tools for your artists, releases, and catalog.

Build Your Platform

Our team builds custom AI software for your business.

API REFERENCE

Exchange player Spotify authorization

On this page
POST/api/players/spotify/session

Internal trusted Recoup player endpoint, not an external website integration. Requires a fresh Spotify listening session, PKCE code/verifier, API-configured OAuth app and required scopes. Captures Spotify-confirmed available profile/email for the registered artist/workspace. Returns provider credentials only to the trusted Recoup browser, plus player_session_id and fanCapture; no email/fan ID in the response. Tokens are not persisted in fan tables. A failed capture reports fanCapture=false while valid playback credentials remain usable. Authorization is not email marketing consent.

Authentication

This endpoint does not require authentication.

Request

cURL
curl --request POST \
  --url 'https://api.recoupable.dev/api/players/spotify/session' \
  --header 'Content-Type: application/json' \
  --data '{
  "code": "string",
  "verifier": "string",
  "flow": "string"
}'

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

cURL for this request
curl --request POST \
  --url 'https://recoup-api.vercel.app/api/players/spotify/session' \
  --header 'Content-Type: application/json' \
  --data '{
  "code": "string",
  "verifier": "string",
  "flow": "string"
}'

Request body required

application/json

codestringrequired

minLength: 1 · maxLength: 2048

verifierstringrequired

minLength: 43 · maxLength: 128

flowstringrequired

minLength: 1 · maxLength: 2048

Responses

200SpotifyPlayerSession fields returned by the release player service.

application/json

access_tokenstringrequired

Private provider access token, delivered only to the trusted Recoup browser. Never embed in an artist website.

refresh_tokenstring

Optional private provider refresh token; same trusted-browser boundary.

expires_innumberrequired
token_typestring
scopestringrequired
player_session_idstringrequired

format: uuid

fanCapturebooleanrequired

True only after the verified fan identity was persisted.

400Invalid input

application/json

errorstringrequired
statusstring
401Missing/invalid authentication or failed provider authorization

application/json

errorstringrequired
statusstring
403Workspace, origin, or session access denied

application/json

errorstringrequired
statusstring
404Player not available

application/json

errorstringrequired
statusstring
429Request rate limit exceeded

application/json

errorstringrequired
statusstring
503Feature/configuration temporarily unavailable

application/json

errorstringrequired
statusstring

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download players.json
View operation source
json
{
  "summary": "Exchange player Spotify authorization",
  "description": "Internal trusted Recoup player endpoint, not an external website integration. Requires a fresh Spotify listening session, PKCE code/verifier, API-configured OAuth app and required scopes. Captures Spotify-confirmed available profile/email for the registered artist/workspace. Returns provider credentials only to the trusted Recoup browser, plus player_session_id and fanCapture; no email/fan ID in the response. Tokens are not persisted in fan tables. A failed capture reports fanCapture=false while valid playback credentials remain usable. Authorization is not email marketing consent.",
  "security": [],
  "parameters": [],
  "responses": {
    "200": {
      "description": "SpotifyPlayerSession fields returned by the release player service.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SpotifyPlayerSession"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PlayerError"
          }
        }
      }
    },
    "401": {
      "description": "Missing/invalid authentication or failed provider authorization",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PlayerError"
          }
        }
      }
    },
    "403": {
      "description": "Workspace, origin, or session access denied",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PlayerError"
          }
        }
      }
    },
    "404": {
      "description": "Player not available",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PlayerError"
          }
        }
      }
    },
    "429": {
      "description": "Request rate limit exceeded",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PlayerError"
          }
        }
      }
    },
    "503": {
      "description": "Feature/configuration temporarily unavailable",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PlayerError"
          }
        }
      }
    }
  },
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "code",
            "verifier",
            "flow"
          ],
          "properties": {
            "code": {
              "type": "string",
              "minLength": 1,
              "maxLength": 2048
            },
            "verifier": {
              "type": "string",
              "minLength": 43,
              "maxLength": 128
            },
            "flow": {
              "type": "string",
              "minLength": 1,
              "maxLength": 2048
            }
          }
        }
      }
    }
  }
}