OAuth

Audius OAuth lets users authorize your app to perform actions on their behalf (write permissions) or simply verify their identity and share their profile info (read-only). The SDK implements the OAuth 2.0 Authorization Code Flow with PKCE — no backend server or client secret is required.

For a step-by-step setup guide, see Log in with Audius.

login(params)

Opens the Audius consent screen and runs the full PKCE authorization flow.

• Popup (default): Opens a popup window. When the user approves, the popup redirects to redirectUri. On that page, handleRedirect() forwards the code to the parent and closes the popup. The login() promise resolves.
• Full-page redirect: Navigates the current page to Audius. After the user approves, Audius redirects back to redirectUri. Call handleRedirect() there to complete the exchange.
• Mobile: Opens an in-app browser session (ASWebAuthenticationSession on iOS, Chrome Custom Tab on Android). The redirect is captured and handleRedirect() is called automatically. login() resolves when the token exchange is complete.

Throws if the flow fails or the user cancels.

Example (popup — recommended for web):

// redirectUri set once in sdk({ redirectUri: '...' })
try {
  await audiusSdk.oauth.login({ scope: 'write' })
  const user = await audiusSdk.oauth.getUser()
  console.log('Signed in as', user.name)
} catch (err) {
  console.error('Login failed or cancelled:', err.message)
}

Example (mobile):

// redirectUri set once in sdk({ redirectUri: 'myapp://oauth/callback' })
await audiusSdk.oauth.login({ scope: 'write', display: 'fullScreen' })
const user = await audiusSdk.oauth.getUser()

Params

Returns

Returns Promise<void>.

getUser()

Fetches the authenticated user's profile from the server using the stored access token. Always makes a network request so the result reflects current server-side state.

Throws ResponseError (4xx/5xx) or FetchError (network failure) if the request fails. A 401 typically means no token is stored or the session has expired.

Example:

const user = await audiusSdk.oauth.getUser()
console.log(`@${user.handle}`)

Returns

Returns Promise<DecodedUserToken>.

type DecodedUserToken = {
  userId: number       // unique Audius user identifier
  name: string         // display name
  handle: string
  verified: boolean    // Audius verified checkmark
  profilePicture?: {
    '150x150': string
    '480x480': string
    '1000x1000': string
    mirrors: string[]
  }
}

handleRedirect(url?)

Completes an OAuth flow by processing the redirect URL. Call this on your callback page after login() redirects there.

• Popup: Detects window.opener, forwards the authorization code back to the parent window via postMessage, and closes the popup. The parent's login() promise resolves.
• Full-page redirect / mobile: Verifies the CSRF state, performs the PKCE token exchange, and stores the tokens. Call getUser() afterwards to retrieve the profile.

Pass the redirect URL explicitly (e.g. a mobile deep link URL) or omit to use the current page URL on web. Is a no-op when no redirect params are present. The result can only be consumed once.

The redirectUri used in the token exchange is resolved in this order:

1. The value stored in session state from the originating login() call
2. The redirectUri set in the top-level SDK config
3. The current page's origin + path (web only, fallback)

On mobile, this is called automatically inside login() — you do not need to call it.

Example:

// On your callback page:
const audiusSdk = sdk({ appName: 'My App', apiKey: 'YOUR_API_KEY' })
await audiusSdk.oauth.handleRedirect()
// Popup: closes and resolves login() in parent — nothing more needed here
// Full-page: token stored — call getUser() to get the profile

Params

Returns

Returns Promise<void>.

isAuthenticated()

Returns true if an access token is currently stored. Tokens are persisted across sessions (localStorage on web, AsyncStorage on React Native), so this will be true on page/app reload if the user previously logged in.

Example:

if (await audiusSdk.oauth.isAuthenticated()) {
  const user = await audiusSdk.oauth.getUser()
}

Returns

Returns Promise<boolean>.

hasRefreshToken()

Returns true if a refresh token is stored and a refresh exchange could be attempted.

Example:

if (await audiusSdk.oauth.hasRefreshToken()) {
  await audiusSdk.oauth.refreshAccessToken()
}

Returns

Returns Promise<boolean>.

hasRedirectResult(url?)

Synchronous check for whether the given URL (or current page URL on web) contains OAuth redirect params (code + state). No network requests or side effects. Useful for showing a loading state before calling handleRedirect().

Example:

if (audiusSdk.oauth.hasRedirectResult()) {
  showLoadingSpinner()
  await audiusSdk.oauth.handleRedirect()
  hideLoadingSpinner()
}

Params

Returns

Returns boolean.

refreshAccessToken()

Refreshes the access token using the stored refresh token. The SDK calls this automatically when API requests return 401, but you can trigger it manually if needed.

Example:

const newToken = await audiusSdk.oauth.refreshAccessToken()
if (!newToken) {
  // Prompt the user to log in again
}

Returns

Returns Promise<string | null> — the new access token, or null if the refresh failed.

logout()

Revokes the current refresh token server-side and clears all stored tokens and PKCE session state. After calling this, all SDK API calls revert to unauthenticated.

Example:

await audiusSdk.oauth.logout()

Returns

Returns Promise<void>.