Reference / @open-music-sdk/user-token / validateUserToken

Function: validateUserToken()

function validateUserToken(
   client, 
   token, 
   options?
): Promise<string>;

Defined in: user-token/src/token.ts:48

Asks Apple whether token works, with GET /v1/me/storefront, and resolves to the listener's storefront.

What a token is, is core's rule: printable characters with no spaces or line breaks inside, and whitespace around it dropped. A token that is not one is the caller's mistake and a TypeError, before Apple is asked; the error describes the value and never repeats it.

UserTokenInvalid is Apple's verdict and nothing else: Apple answered 403, or answered 401 for the listener while accepting the developer token. Any other failure (developer token, rate limit, network, a reply with no storefront) is the client's usual error and says nothing about the token.

Apple documents two causes for a 401 under /v1/me: the developer token, or a listener who is not signed in or has no subscription. So after a 401 it asks once more, with the developer token alone (GET /v1/test):

Apple answers	Outcome
2xx naming a storefront	Resolves to the storefront's id
2xx naming none	ApiError; the token is not taken as accepted
403, as a token Apple never gave was answered against the live API on 18 October 2026	UserTokenInvalid, with status 403
401, and accepts the developer token on its own	UserTokenInvalid, with status 401
401, and refuses the developer token on its own too	What that second request failed with, such as DeveloperTokenInvalid
Anything else	The client's usual error, which says nothing about the token

Parameters

client

tAppleMusicClient

The client to ask with. Its developer token is sent; token stands in for any listener it is bound to.

token

string

The Music User Token to ask about.

options?

tValidateOptions = {}

A signal to abort with.

Returns

Promise<string>

The listener's storefront id, such as us.

Throws

TypeError if client is not a client, token is not a token, options is not a plain object, or options.signal is no AbortSignal, before Apple is asked.

Throws

AppleMusicError UserTokenInvalid when Apple will not take the token; otherwise what asking failed with: DeveloperTokenInvalid, DeveloperTokenUnavailable, RateLimited, NetworkError, or ApiError, which a 2xx that names no storefront is too. _tag says which.

Throws

Whatever a token provider, hook or rate limiter throws, as client.request passes it on.

Throws

The reason options.signal aborted with, when it does.