Skip to main content

OAuth

Enable users to either authorize your app to perform actions on their behalf (i.e. grant write permissions), or simply verify who they are and give you access to their Audius profile info (no write permissions granted).

Methods

init

init(params)

Enables the Audius OAuth functionality. Call this before using any other oauth methods.

Params

  • successCallback (profile: UserProfile, encodedJwt: string) => void - function to be called when the user successfully authorizes or authenticates with Audius. This function will be called with the user's profile information, which is an object with the following shape:

    // `UserProfile` type:
    {
    userId: number; // unique Audius user identifier
    email: string;
    name: string; // user's display name
    handle: string;
    verified: boolean; // whether the user has the Audius "verified" checkmark

    /** URLs for the user's profile picture, if any.
    * If the user has a profile picture, three sizes will be available: 150x150, 480x480, and 1000x1000.
    * If the user has no profile picture, this field will be empty.
    */
    profilePicture: {"150x150": string, "480x480": string, "1000x1000": string } | { misc: string } | undefined | null
    apiKey: string | null // the API key for your application if specified
    sub: number; // alias for userId
    iat: string; // timestamp for when auth was performed
    }

    The second argument (encodedJwt) is for advanced use cases that want to pass the JWT to a backend for server-side verification.

  • errorCallback optional (errorMessage: string) => void - function to be called when an error occurs during the authentication flow. This function will be called with a string describing the error.

Returns: Nothing

Example

audiusSdk.oauth.init({
successCallback: (user) => console.log('Logged in user', user),
errorCallback: (error) => console.log('Got error', error),
})

renderButton

renderButton(params)

Replaces the element passed in the first parameter with the Log In with Audius button.

Params

  • element HTMLElement - HTML element to replace with the Log In with Audius button

  • scope optional 'write' | 'read' - Whether your app is requesting read or write permissions to the user's account. Specify "write" if you'd like the user to authorize your app to perform actions on their behalf, such as uploading a track or favoriting a playlist. Specify "read" if you simply need the user's email and profile information, and do not need any write permissions. Defaults to "read".

  • buttonOptions optional ButtonOptions - optional object containing the customization settings for the button to be rendered. Here are the options available:

    // type ButtonOptions =
    {
    // Size of the button:
    size?: "small | 'medium' | 'large'

    // Corner style of the button:
    corners?: 'default' | 'pill'

    // Your own text for the button; default is "Log In with Audius":
    customText?: string

    // Whether to disable the button's "grow" animation on hover:
    disableHoverGrow?: boolean

    // Whether the button should take up the full width of its parent element:
    fullWidth?: boolean
    }

    Use this playground to see how these customizations affect the button appearance and determine what config works best for your app.

note

The write scope grants your app permission to perform most actions on the user's behalf, but it does NOT allow any access to DMs or wallets.

Returns: Nothing

Example

audiusSdk.oauth.renderButton({
element: document.getElementById('audiusLogInButton'),
scope: 'write',
buttonOptions: {
size: 'large',
},
})

login

login(params)

Opens the Log In with Audius popup, which begins the authentication flow. Use this if you have your own link or button implementation, and don't want to use renderButton.

Params

  • scope optional 'write' | 'read' - Whether your app is requesting read or write permissions to the user's account. Specify "write" if you'd like the user to authorize your app to perform actions on their behalf, such as uploading a track or favoriting a playlist. Specify "read" if you simply need the user's email and profile information, and do not need any write permissions. Defaults to "read".
note

The write scope grants your app permission to perform most actions on the user's behalf, but it does NOT allow any access to DMs or wallets.

Returns: Nothing

Example

script.js
function logInWithAudius() {
audiusSdk.oauth.login({ scope: 'write' })
}
index.html
<button onclick="logInWithAudius()">Continue with Audius!</button>

isWriteAccessGranted

isWriteAccessGranted(params)

Checks whether your app has write permissions to the given user's account.

Params

  • userId string - User's Audius user ID

Returns: Promise<boolean>

Example

async function hasSkrillexAuthorizedApp() {
await audiusSdk.oauth.isWriteAccessGranted({ userId: 'eAZl3' })
}