> ## 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.

# Authentication

> OAuth 2.0 integration guide for Musixmatch enterprise partners

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](mailto: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 code
* `state` — 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` |

**Response:**

```json theme={null}
{
  "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 |

<Warning>
  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.
</Warning>

## 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 |

**Response (valid token):**

```json theme={null}
{
  "active": true,
  "sub": "<musixmatch-user-id>"
}
```

**Response (invalid token):**

```json theme={null}
{
  "active": false
}
```

## 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 |

**Response:**

```json theme={null}
{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "..."
}
```

Pass the resulting `access_token` as a Bearer token in the `Authorization` header of API requests:

```
Authorization: Bearer <access_token>
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.