Raw service tokens and refresh

MusicAPI keeps each user's music-service tokens and renews them for you. Most integrations never touch them. Read them only to call a service endpoint that MusicAPI does not cover.

From your backend (Client Secret)

GET/public/integrations/user/{integrationUserUUID} with Basic authentication returns authData.

curl "https://api.musicapi.com/public/integrations/user/3f0b8c1e-6a4d-4c7a-9a55-2f1e7d9b0c11" \
  -u "$MUSICAPI_CLIENT_ID:$MUSICAPI_CLIENT_SECRET"

{
  "integrationUser": {
    "uuid": "3f0b8c1e-6a4d-4c7a-9a55-2f1e7d9b0c11",
    "integrationUserId": "mica.nowak",
    "name": "Mica Nowak",
    "email": "[email protected]",
    "imageUrl": "https://images.example.com/mica.jpg",
    "country": "PL",
    "authData": { "accessToken": "BQD…" },
    "authDataExpiresAt": 1792137600000
  },
  "integration": { "type": "spotify" }
}

• authData holds the service's credentials without the refresh token. The fields depend on the service.
• authDataExpiresAt is when the access token expires, in milliseconds since the epoch.
• When the token expires within one minute, MusicAPI renews it before it answers.

From an app without a backend (one-time token)

1. Ask for a token

   Add requestOneTimeToken=true to the sign-in URL.

2. Read it from the callback

   The decoded data64 holds oneTimeToken.

3. Spend it at once

   Call the connected-user endpoint with Authorization: Token <oneTimeToken> within 30 seconds.

https://app.musicapi.com/{slug}?returnUrl={returnUrl}&requestOneTimeToken=true

curl "https://api.musicapi.com/public/integrations/user/3f0b8c1e-6a4d-4c7a-9a55-2f1e7d9b0c11" \
  -H "Authorization: Token e50cc5e7-254a-4cff-a000-457ae53a059d"

The one-time token is bound to the sign-in it came from. For another connected user it answers 403. You can also pass it as ?oneTimeToken= to GET/public/integrations/auth/{authModelUUID}.

Attach-only tokens for browser sign-ins

You can keep the music-service tokens out of the browser. In the dashboard, open API & webhooks and turn on Browser logins can only attach. The setting is off by default.

When it is on, the oneTimeToken of a sign-in that returns to a web page (an http or https returnUrl) does not read authData. GET/public/integrations/user/{integrationUserUUID} and GET/public/integrations/auth/{authModelUUID} answer that token without authData and authDataExpiresAt. The token still proves the sign-in. Read the raw tokens from your backend with your Client Secret.

A sign-in that returns to a native app (a custom scheme such as myapp://) keeps the full token.

Force a refresh

POST/public/integrations/refreshAuthToken renews the tokens of one user now, for example after the service told you the token is no longer valid.

curl -X POST "https://api.musicapi.com/public/integrations/refreshAuthToken" \
  -u "$MUSICAPI_CLIENT_ID:$MUSICAPI_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"integrationUserUUID": "3f0b8c1e-6a4d-4c7a-9a55-2f1e7d9b0c11"}'

• With Basic the answer holds the new authData. Other credentials get the profile only.
• When the service refuses the renewal, the answer is 401. The user must sign in again.

You never need this for MusicAPI's own library calls: they renew an expired token by themselves.