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>
