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