Documentation Index
Fetch the complete documentation index at: https://docs.musixmatch.com/llms.txt
Use this file to discover all available pages before exploring further.
Musixmatch enterprise integrations use OAuth 2.0 for authentication and authorization. Two grant types are supported depending on your use case.
The authorization server base URL is:
https://connect.musixmatch.com
| Endpoint | Description |
|---|
GET /oauth/authorize | Authorization endpoint |
POST /oauth/token | Token issuance and refresh |
POST /oauth/token-metadata | Token introspection |
GET /.well-known/oauth-authorization-server | OAuth 2.0 metadata |
GET /.well-known/openid-configuration | OpenID Connect metadata |
Client Registration
Before integrating, Musixmatch will issue you a Client ID and Client Secret during the client registration process. You will also need to provide your redirect_uri (required for the Authorization Code flow).
Contact apisupport@musixmatch.com to begin registration.
Authorization Code Flow
Use this flow to authenticate end users (artists or rights holders) within your application. The result is an access_token bound to that user, which can be introspected to retrieve their Musixmatch user ID.
Step 1 — Initiate the authorization request
Redirect the user to the Musixmatch authorization endpoint:
GET https://connect.musixmatch.com/oauth/authorize
| Parameter | Required | Description |
|---|
response_type | Yes | Must be code |
client_id | Yes | Your client identifier |
redirect_uri | Yes | Your pre-registered callback URL |
scope | Yes | Must include profile email |
state | Yes | Random value to prevent CSRF — verify it on callback |
code_challenge | Recommended | Base64url-encoded SHA256 hash of code_verifier (PKCE) |
code_challenge_method | Recommended | Must be S256 if using PKCE |
Step 2 — User authorizes
The user logs in or registers on Musixmatch. On success, they are redirected to your redirect_uri with:
code — the authorization codestate — must match the value you sent in Step 1
Step 3 — Exchange the code for tokens
POST https://connect.musixmatch.com/oauth/token
Content-Type: application/x-www-form-urlencoded
| Parameter | Required | Description |
|---|
grant_type | Yes | Must be authorization_code |
client_id | Yes | Your client identifier |
client_secret | Yes | Your client secret |
code | Yes | The authorization code from Step 2 |
redirect_uri | Yes | Must exactly match the URI used in Step 1 |
code_verifier | If PKCE used | The original unhashed secret used to generate code_challenge |
{
"access_token": "...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "...",
"scope": "profile email"
}
Step 4 — Refresh the access token
When the access_token expires, use the refresh_token to get a new one without requiring the user to log in again.
POST https://connect.musixmatch.com/oauth/token
Content-Type: application/x-www-form-urlencoded
| Parameter | Required | Description |
|---|
grant_type | Yes | Must be refresh_token |
refresh_token | Yes | The refresh token from Step 3 |
client_id | Yes | Your client identifier |
client_secret | Yes | Your client secret |
Following the OAuth specification and security best practices, the refresh_token used in a successful request will be invalidated — alongside all related access tokens — and a new one will be issued in the response. Always store and use the latest refresh_token returned.
Retrieving the Musixmatch User ID
Once you have a user access_token, introspect it to retrieve the Musixmatch user ID (sub). This ID is required when making API calls on behalf of a user.
POST https://connect.musixmatch.com/oauth/token-metadata
Content-Type: application/x-www-form-urlencoded
| Parameter | Required | Description |
|---|
accessToken | Yes | The user’s access token |
{
"active": true,
"sub": "<musixmatch-user-id>"
}
Client Credentials Flow
Use this flow for server-to-server API calls that do not require a user context — for example, submitting a release delivery or lyrics from your backend.
POST https://connect.musixmatch.com/oauth/token
Content-Type: application/x-www-form-urlencoded
| Parameter | Required | Description |
|---|
grant_type | Yes | Must be client_credentials |
client_id | Yes | Your client identifier |
client_secret | Yes | Your client secret |
scope | No | Space-separated list of requested permissions |
{
"access_token": "...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "..."
}
access_token as a Bearer token in the Authorization header of API requests:
Authorization: Bearer <access_token>
