Skip to main content

3rd Party Integration Guide

This guide walks you through setting up a third party, Spotify, OAuth2 integration with Auth Kit from scratch.

Prerequisites​

  • Spectacles device with Auth Kit support
  • Lens Studio project with AuthorizationKit and SpectaclesInteractionKit packages
  • Spotify Developer account
  • Basic understanding of OAuth2 flows

Step 1: Create a Spotify App​

1.1 Access Spotify Developer Dashboard​

  1. Go to Spotify Developer Dashboard
  2. Log in with your Spotify account
  3. Click "Create app"

1.2 Configure Your App​

Fill out the app creation form:

  • App name: Choose a descriptive name for your Lens (e.g., "My Music Lens")
  • App description: Describe what your Lens does with Spotify
  • Website: Enter your website or use a placeholder
  • Redirect URI: Important! Use exactly this URI: 
    https://www.spectacles.com/deeplink/specslink/oauth2redirect/unsecure

1.3 Accept Terms and Create​

  1. Check the boxes to agree to Spotify's Terms of Service and Developer Terms
  2. Click "Save" to create your app

Step 2: Get OAuth2 Credentials​

2.1 Access App Settings​

  1. Click on your newly created app in the dashboard
  2. Go to "Settings"
  3. Note down the following credentials:

2.2 Required Credentials​

You'll need these four pieces of information:

const spotifyConfig = {
  clientId: 'your-client-id-here', // From app settings
  authorizationUri: 'https://accounts.spotify.com/authorize',
  tokenUri: 'https://accounts.spotify.com/api/token',
  scope: 'user-read-private user-read-email', // See scopes section below
};

Step 3: Understanding Scopes​

Spotify uses scopes to control what data your app can access. Choose only the scopes you need:

Always check the Spotify Web API Scopes documentation for the most up-to-date list of available scopes and their descriptions.

Common Scopes​

ScopeDescription
user-read-privateAccess user's subscription details and country
user-read-emailAccess user's email address
user-read-playback-stateRead user's current playback state
user-modify-playback-stateControl user's playback (play, pause, skip)
user-read-currently-playingRead user's currently playing track
user-read-recently-playedAccess user's recently played tracks
user-top-readAccess user's top artists and tracks
playlist-read-privateAccess user's private playlists
playlist-read-collaborativeAccess user's collaborative playlists

Example Scope Combinations​

// For a music discovery Lens
const discoverScopes =
  'user-read-private user-top-read user-read-recently-played';

// For a playback control Lens
const playbackScopes =
  'user-read-playback-state user-modify-playback-state user-read-currently-playing';

// For a playlist viewer Lens
const playlistScopes =
  'user-read-private playlist-read-private playlist-read-collaborative';

Step 4: Implement OAuth2 in Your Lens​

Complete UIController Implementation​

Here's a complete implementation using the UIController pattern that handles Spotify OAuth2 authentication:

import { OAuth2 } from 'AuthKit.lspkg/Core/OAuth2';
import { SIK } from 'SpectaclesInteractionKit.lspkg/SIK';

@component
export class SpotifyUIController extends BaseScriptComponent {
  @input signInButton: SceneObject;
  @input signOutButton: SceneObject;
  @input apiButton: SceneObject;
  @input statusText: Text;
  @input titleText: Text;

  @ui.separator
  @input
  title: string = 'Spotify Music Lens';

  @ui.separator
  @input
  clientId: string = 'your-spotify-client-id'; // Replace with your Spotify Client ID
  @input authorizationUri: string = 'https://accounts.spotify.com/authorize';
  @input tokenUri: string = 'https://accounts.spotify.com/api/token';
  @input authenticationType: string = 'code';

  @ui.separator
  @input
  scope: string =
    'user-read-private user-read-currently-playing user-read-playback-state';

  @ui.separator
  @input
  apiUri: string = 'https://api.spotify.com/v1/me';
  @input apiResponseKey: string = 'display_name';

  private internetModule: InternetModule = require('LensStudio:InternetModule');
  private oauth: OAuth2;

  onAwake() {
    // Initialize OAuth2 with Spotify configuration
    this.oauth = new OAuth2({
      clientId: this.clientId,
      authorizationUri: this.authorizationUri,
      tokenUri: this.tokenUri,
      authenticationType: this.authenticationType,
    });

    this.createEvent('OnStartEvent').bind(() => {
      this.bindButtons();
    });

    // Update initial UI state
    this.statusText.text = this.oauth.isAuthorized
      ? 'Signed In'
      : 'Tap Sign In to connect Spotify';
    this.titleText.text = this.title;
  }

  private bindButtons() {
    // Bind Sign In button
    SIK.InteractionManager.getInteractableBySceneObject(
      this.signInButton
    ).onTriggerEnd(this.onSignIn.bind(this));

    // Bind Sign Out button
    SIK.InteractionManager.getInteractableBySceneObject(
      this.signOutButton
    ).onTriggerEnd(this.onSignOut.bind(this));

    // Bind API Test button
    SIK.InteractionManager.getInteractableBySceneObject(
      this.apiButton
    ).onTriggerEnd(this.onAPI.bind(this));
  }

  private onSignIn() {
    this.statusText.text = 'Connecting to Spotify...';

    this.oauth
      .authorize(this.scope)
      .then(() => {
        this.statusText.text = '✅ Successfully connected to Spotify!';
      })
      .catch((error) => {
        this.statusText.text = '❌ Connection failed:\n' + error;

        // Handle common errors
        if (
          error
            .toString()
            .includes('Authorization not supported in editor mode')
        ) {
          this.statusText.text =
            "⚠️ Test on Spectacles device\nOAuth2 doesn't work in Lens Studio";
        }
      });
  }

  private onSignOut() {
    this.oauth.signOut();
    this.statusText.text = 'Signed out from Spotify';
  }

  private onAPI() {
    this.statusText.text = 'Getting your Spotify profile...';

    this.getUserData()
      .then((displayName) => {
        this.statusText.text = `Hello, ${displayName}! 🎵`;
      })
      .catch((error) => {
        this.statusText.text = 'API error:\n' + error;
      });
  }

  private async getUserData(): Promise<string> {
    const token = await this.oauth.getAccessToken();

    const request = new Request(this.apiUri, {
      headers: {
        Authorization: 'Bearer ' + token,
        'Content-Type': 'application/json',
      },
    });

    const response = await this.internetModule.fetch(request);
    const data = await response.text();

    print('Spotify API response: ' + data);

    const userData = JSON.parse(data);
    return userData[this.apiResponseKey] || 'Spotify User';
  }
}

Configuration in Lens Studio​

In the Inspector panel, configure your Spotify credentials:

  1. Client ID: Your Spotify app's Client ID from the Developer Dashboard
  2. Authorization URI: https://accounts.spotify.com/authorize
  3. Token URI: https://accounts.spotify.com/api/token
  4. Authentication Type: code
  5. Scope: user-read-private user-read-currently-playing user-read-playback-state
  6. API URI: https://api.spotify.com/v1/me (for testing user profile)
  7. API Response Key: display_name (to display user's name)

Button Behaviors Explained​

onSignIn()​

  • Updates status to show "Connecting to Spotify..."
  • Calls oauth.authorize() with the specified scopes
  • On success: Shows "Successfully connected to Spotify!"
  • On error: Displays the error message with user-friendly handling for common issues

onSignOut()​

  • Calls oauth.signOut() to clear stored tokens
  • Updates status to show "Signed out from Spotify"

onAPI()​

  • Updates status to show "Getting your Spotify profile..."
  • Calls getUserData() to fetch user's Spotify profile
  • On success: Displays "Hello, [User's Name]! 🎵"
  • On error: Shows the API error message

Step 5: Testing Your Integration​

Testing Checklist​

  1. ✅ Verify Redirect URI: Ensure it matches exactly in Spotify app settings
  2. ✅ Test on Device: OAuth2 only works on actual Spectacles, not in editor
  3. ✅ Check Scopes: Verify you're requesting appropriate permissions
  4. ✅ Handle Errors: Test error scenarios (denied access, network issues)
  5. ✅ Token Refresh: Ensure automatic token refresh works for long sessions

Debugging Tips​

// Check authorization status
if (this.oauth.isAuthorized) {
  print('✅ User is authenticated');
} else {
  print('❌ User needs to authenticate');
}

// Validate token manually
const token = await this.oauth.getAccessToken();
if (token) {
  print(`Token available: ${token.substring(0, 10)}...`);
} else {
  print('No valid token available');
}

Common Issues​

"Invalid Redirect URI"​

  • Double-check the redirect URI in your Spotify app settings
  • It must be exactly: https://www.spectacles.com/deeplink/specslink/oauth2redirect/unsecure

"Authorization doesn't work in editor"​

  • OAuth2 requires testing on actual Spectacles device
  • Use device logs to debug issues

"Invalid Client ID"​

  • Copy the Client ID exactly from Spotify Developer Dashboard
  • Ensure no extra spaces or characters

Rate Limiting​

  • Spotify has rate limits on API calls
  • Implement proper error handling for 429 responses
  • Cache data when possible to reduce API calls
Was this page helpful?
Yes
No