Authentication

Authentication should be the first step before making any kind of request. We strongly recommend that partners authenticate when operating in both the sandbox environment and production environment, even for simple catalog reading operations. Doing so grants partners the correct permissions to access their custom Musement catalog data.

Application value

All requests, authenticated or not, require the X-Musement-Application header. More info about this header can be found here.

Musement uses the OAuth 2.0 authorization framework to give applications limited access via API. Check out RFC-6749 and DigitalOcean for an in-depth overview of the framework.

To begin the authentication process, use the endpoint /login. While this endpoint accepts the GET method, it is considered deprecated and may be removed in the future. Partners are encouraged to use the POST method instead:

Copy

Copied

curl -X POST '{baseUrl}/login' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Content-Type: application/json' \
--data-raw '{
	"client_id": "{clientId}",
	"client_secret": "{clientSecret}",
	"grant_type": "client_credentials"
}'

The body request properties client_id, client_secret and grant_type are mandatory. The exact values for the client_id and client_secret properties are provided to partners by our Strategic partnerships team.

The response contains access details:

Copy

Copied

{ 
	"access_token": "OGYzMGM5YjEyZjkzYzI0MGU0N2Y4NDdmZmQ1MjVhYTkzNTY5NWVhYTZmNGIzNWU0MzIxZTFhZjg3NzYyOGYyYQ", 
	"expires_in": 3600, 
	"token_type": "bearer", 
	"scope": null
}

The access_token value in the response must be used for all subsequent requests. The token_type value of bearer indicates the access_token must be added to the Authorization HTTP header, preceded by the word Bearer and a space:

Copy

Copied

curl -X GET '{baseUrl}/activities' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}'

Most tokens expire after 3600 seconds. However, we recommend using the expires_in value in the authentication response to keep accurate track of when a token will expire.

Once a token expires, repeat the authentication process to receive a new valid token.