soundcloud-api-ts-next
    Preparing search index...

    Class SCAuthManager

    Server-side SoundCloud OAuth 2.1 + PKCE auth manager.

    Handles the full authorization code + PKCE flow:

    1. initLogin() — generates a PKCE verifier/challenge + CSRF state, returns the SoundCloud authorize URL.
    2. exchangeCode(code, state) — verifies the CSRF state, exchanges the authorization code + PKCE verifier for access/refresh tokens.
    3. refreshToken(refreshToken) — refreshes an expired access token.

    In-memory store (default): The PKCE verifier is stored in-process memory (tied to the process). In a typical Next.js deployment the module is a long-lived singleton — verifiers survive across requests for up to 10 minutes before being evicted. This breaks on serverless / multi-instance deployments.

    Distributed deployments: Pass a custom PkceStore via SCAuthManagerConfig.pkceStore. See CookiePkceStore for a zero-infrastructure option that stores the verifier in a signed HTTP cookie, or build a Redis adapter for multi-region Node deployments.

    Cookie security options for production: When setting state or verifier cookies in your route handler, always use:

    Set-Cookie: sc_oauth_state=<value>;
      HttpOnly;
      Secure (when NODE_ENV === "production");
      SameSite=Lax;
      Max-Age=600 (10 minutes — matches PKCE TTL)
      Path=/

    Never expose auth cookies to JavaScript (HttpOnly). Always require HTTPS in production (Secure). Use SameSite=Lax to protect against CSRF.

    // lib/sc-auth.ts (module-level singleton)
    import { createSCAuthManager } from "soundcloud-api-ts-next/server";

    export const scAuth = createSCAuthManager({
      clientId: process.env.SC_CLIENT_ID!,
      clientSecret: process.env.SC_CLIENT_SECRET!,
      redirectUri: process.env.SC_REDIRECT_URI!,
    });

    // api/auth/login/route.ts
    const { url, state } = await scAuth.initLogin();
    // Set httpOnly cookie with state, then redirect to url

    // api/auth/callback/route.ts
    const tokens = await scAuth.exchangeCode(code, state);
    // Use tokens.access_token for authenticated SC API calls
    Index

    Constructors

    constructor

    Properties

    stateCookieName

    Accessors

    pendingLogins

    Methods

    exchangeCode initLogin refreshToken

    Constructors

    Properties

    stateCookieName: string

    The name of the cookie to use for storing the OAuth state token. Configured via SCAuthManagerConfig.stateCookieName.

    Accessors

    • get pendingLogins(): number

      Returns the number of active (non-expired) PKCE entries. Useful for observability / health checks. Only meaningful when using the default in-memory store.

      Returns number

    Methods

    • Exchange an authorization code for access + refresh tokens.

      Verifies state against the stored PKCE entry (CSRF check), then exchanges the code + PKCE verifier with SoundCloud's token endpoint. The PKCE entry is consumed (one-time use).

      Parameters

      • code: string

        The code query param from SoundCloud's OAuth redirect.

      • state: string

        The state query param — must match what was returned by initLogin.

      Returns Promise<SoundCloudToken>

      If state is invalid/expired or the token exchange fails.

    • Start the SoundCloud OAuth 2.1 + PKCE login flow.

      Generates a PKCE code_verifier + code_challenge and a random CSRF state token, stores the verifier server-side via the configured PkceStore, and returns the SoundCloud authorize URL to redirect the user to.

      You must persist state (e.g. httpOnly cookie) and verify it in the callback — otherwise CSRF protection is bypassed.

      Parameters

      • Optionaloptions: SCLoginOptions

        Optional login options (e.g. sessionId for multi-tenant).

      Returns Promise<SCLoginResult>

      { url, state } — redirect to url, persist state.

    • Refresh an expired access token using a refresh token.

      Parameters

      • refreshToken: string

        The refresh token obtained from a previous token exchange.

      Returns Promise<SoundCloudToken>

      If the refresh token is expired or invalid.

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Accessors
    Methods