Inherits from NSObject
Declared in SPTAuth.h

Overview

This class provides helper methods for authenticating users against the Spotify OAuth authentication service.

Tasks

Convenience Getters

Environment settings

Starting Authentication

Handling Authentication Callback URLs

Renewing Sessions

Properties

clientID

Your client ID.

@property (strong, readwrite) NSString *clientID

Declared In

SPTAuth.h

hasTokenRefreshService

Returns true if there’s a valid token refresh url specified.

@property (readonly) BOOL hasTokenRefreshService

Declared In

SPTAuth.h

hasTokenSwapService

Returns true if there’s a valid token swap url specified.

@property (readonly) BOOL hasTokenSwapService

Declared In

SPTAuth.h

redirectURL

Your redirect URL.

@property (strong, readwrite) NSURL *redirectURL

Declared In

SPTAuth.h

requestedScopes

Required scopes for the app, used by authentication steps

@property (strong, readwrite) NSArray *requestedScopes

Declared In

SPTAuth.h

session

The current session, Note: setting this will persist it in NSUserDefaults standardUserDefaults if a sessionUserDefaultsKey is set.

@property (strong, readwrite) SPTSession *session

Declared In

SPTAuth.h

sessionUserDefaultsKey

User defaults key, if you want to automatically save the session from user defaults when it changes.

@property (strong, readwrite) NSString *sessionUserDefaultsKey

Declared In

SPTAuth.h

tokenRefreshURL

Your token refresh URL, if not specified the refresh token flow will be disabled.

@property (strong, readwrite) NSURL *tokenRefreshURL

Declared In

SPTAuth.h

tokenSwapURL

Your token swap URL, if not specified the authentication flow will be limited to implicit grant flow.

@property (strong, readwrite) NSURL *tokenSwapURL

Declared In

SPTAuth.h

Class Methods

defaultInstance

Returns a pre-created SPTAuth instance for convenience.

+ (SPTAuth *)defaultInstance

Return Value

A pre-created default SPTAuth instance.

Declared In

SPTAuth.h

loginURLForClientId:withRedirectURL:scopes:responseType:

Returns a URL that, when opened, will begin the Spotify authentication process.

+ (NSURL *)loginURLForClientId:(NSString *)clientId withRedirectURL:(NSURL *)redirectURL scopes:(NSArray *)scopes responseType:(NSString *)responseType

Parameters

clientId

Your client ID as declared in the Spotify Developer Centre.

redirectURL

Your callback URL as declared in the Spotify Developer Centre.

scopes

The custom scopes to request from the auth API.

responseType

Authentication response code type, defaults to “code”, use “token” if you want to bounce directly to the app without refresh tokens.

Return Value

The URL to pass to UIApplication’s -openURL: method.

Discussion

Warning: You must open this URL with the system handler to have the auth process happen in Safari. Displaying this inside your application is against the Spotify ToS.

Declared In

SPTAuth.h

loginURLForClientId:withRedirectURL:scopes:responseType:campaignId:

Returns a URL that, when opened, will begin the Spotify authentication process.

+ (NSURL *)loginURLForClientId:(NSString *)clientId withRedirectURL:(NSURL *)redirectURL scopes:(NSArray *)scopes responseType:(NSString *)responseType campaignId:(NSString *)campaignId

Parameters

clientId

Your client ID as declared in the Spotify Developer Centre.

redirectURL

Your callback URL as declared in the Spotify Developer Centre.

scopes

The custom scopes to request from the auth API.

responseType

Authentication response code type, defaults to “code”, use “token” if you want to bounce directly to the app without refresh tokens.

campaignId

A Spotify-provided campaign token.

Return Value

The URL to pass to UIApplication’s -openURL: method.

Discussion

Warning: You must open this URL with the system handler to have the auth process happen in Safari. Displaying this inside your application is against the Spotify ToS.

Declared In

SPTAuth.h

spotifyApplicationIsInstalled

Check if Spotify application is installed.

+ (BOOL)spotifyApplicationIsInstalled

Return Value

YES if installed, NO otherwise.

Declared In

SPTAuth.h

supportsApplicationAuthentication

Check if “flip-flop” application authentication is supported.

+ (BOOL)supportsApplicationAuthentication

Return Value

YES if supported, NO otherwise.

Declared In

SPTAuth.h

Instance Methods

canHandleURL:

Find out if the given URL appears to be a Spotify authentication URL.

- (BOOL)canHandleURL:(NSURL *)callbackURL

Parameters

callbackURL

The complete callback URL as triggered in your application.

Return Value

Returns YES if the callback URL appears to be a Spotify auth callback, otherwise NO.

Discussion

This method is useful if your application handles multiple URL types. You can pass every URL you receive through here to filter them.

Declared In

SPTAuth.h

handleAuthCallbackWithTriggeredAuthURL:callback:

Handle a Spotify authentication callback URL, returning a Spotify username and OAuth credential.

- (void)handleAuthCallbackWithTriggeredAuthURL:(NSURL *)url callback:(SPTAuthCallback)block

Parameters

url

The complete callback URL as triggered in your application.

block

The callback block to be triggered when authentication succeeds or fails.

Discussion

This URL is obtained when your application delegate’s application:openURL:sourceApplication:annotation: method is triggered. Use [SPTAuth canHandleURL:] to easily filter out other URLs that may be triggered.

Declared In

SPTAuth.h

renewSession:callback:

Request a new access token using an existing SPTSession object containing a refresh token.

- (void)renewSession:(SPTSession *)session callback:(SPTAuthCallback)block

Parameters

session

An SPTSession object with a valid refresh token.

block

The callback block that will be invoked when the request has been performed.

Discussion

If no token refresh service has been specified the callback will return nil as session.

Declared In

SPTAuth.h

spotifyAppAuthenticationURL

Returns a spotify-action:// URL that you can use to retrieve an access token if [SPTAuth supportsApplicationAuthentication] returns YES.

- (NSURL *)spotifyAppAuthenticationURL

Return Value

spotify-action:// URL for initiating a Spotfiy Client SSO attempt.

Discussion

Pass this URL to [UIApplication openURL:] to launch the Spotify application on the device.

Note: This will authenticate and authorise for the user currently logged in to the Spotfiy application. There might be no option to switch user.

Declared In

SPTAuth.h

spotifyWebAuthenticationURL

Returns a https:// URL that you can use to retrieve an access token.

- (NSURL *)spotifyWebAuthenticationURL

Return Value

https:// URL for authenticating and authorising with the Spotify service

Discussion

Display this URL within a SFSafariViewController on iOS 9 and up, or UIWebView.

This is the preffered mode of authentication.

Note: This will always display an option to switch user.

Declared In

SPTAuth.h