# Exchange player Spotify authorization

Source: https://recoupable.dev/docs/api-reference/complete/players/post-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.

## POST /api/players/spotify/session

Full OpenAPI specification: https://recoupable.dev/docs/spec/players.json

## Authentication

This operation's specification permits a request without authentication.

[Authentication guide](https://recoupable.dev/docs/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Recoup API - Release Players",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.recoupable.dev"
    }
  ],
  "paths": {
    "/api/players/spotify/session": {
      "post": {
        "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
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SpotifyPlayerSession": {
        "type": "object",
        "properties": {
          "access_token": {
            "type": "string",
            "description": "Private provider access token, delivered only to the trusted Recoup browser. Never embed in an artist website."
          },
          "refresh_token": {
            "type": "string",
            "description": "Optional private provider refresh token; same trusted-browser boundary."
          },
          "expires_in": {
            "type": "number"
          },
          "token_type": {
            "type": "string"
          },
          "scope": {
            "type": "string"
          },
          "player_session_id": {
            "type": "string",
            "format": "uuid"
          },
          "fanCapture": {
            "type": "boolean",
            "description": "True only after the verified fan identity was persisted."
          }
        },
        "required": [
          "access_token",
          "expires_in",
          "scope",
          "player_session_id",
          "fanCapture"
        ]
      },
      "PlayerError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      }
    }
  }
}
```