Authentication

Introduction

The main concept of our authentication is based on an organization having users, and owning catalogs and clients. The configuration is either linked to an agreement or to the organization itself.

An Organization is any external entity willing to use or using our services. It contains the main configuration for all the licenced products.

A User is a physical person acting in the organization's name and having access to our Portal. A user can be part of several organizations.

A Catalog is a collection of tracks that you will target while querying our services and can be either owned (private) or shared (public).

A Client is any application - in any specific stage - that has access to our Web API.

An Agreement is the digital contract between your organization and Musimap. It contains all the parameters related to your licence.

Clients

Each request made to our Web API requires to be authenticated by using a specific client that could reflect its usage and/or its environment. We usually advise our customers to create one client per application and per environment (dev / staging / production).

Connect to our portal to create one:

Screenshot

Once submitted, you will receive a unique client_id and client_secret. Please note that those credentials are confidential and that you are responsible for any requests that are made through it. Keep them safe and don't share them with anyone.

Screenshot

Usage

Generate an Access Token

Let's now do our first query to generate an Access Token.

curl --location --request POST 'https://api-v2.musimap.io/oauth/access_tokens/client' \
--header 'Content-Type: application/json' \
--data-raw '{
  "client_id": "{YOUR_CLIENT_ID}",
  "client_secret": "{YOUR_CLIENT_SECRET}"
}'

Replace {YOUR_CLIENT_ID} and {YOUR_CLIENT_SECRET} here above and run the command to generate a new token.

{
    "status": 201,
    "timestamp": 1605548750797,
    "data": {
        "id": "232a15c2-2f34-47ef-968b-86c3290d1058",
        "removed_at": null,
        "refreshed_at": null,
        "revoked_at": null,
        "subject_type": "Client",
        "subject_id": "efb3ed15-0052-4e00-9584-1365510b547d",
        "issued_at": 1605548750779,
        "expires_at": 1605555950779,
        "issuer_type": null,
        "issuer_id": null,
        "organization_id": "e4587784-e0a4-43ff-8466-bf17afbb352c",
        "token": "eyJqdGkiOiIyMzJhMTVjMi0yZTM0LTQ3ZWYtOTY4NTItNGUwMC05NTg0LTEzNjU1MTBiNTQ3ZCIsImV4cCI6MTYwNTU1NTk1MCwiaWF0IjoxNjA1NTQ4NzUwfQ==.mWSJ8A6Yz8SMgly4PqOiyP1KSFMJdaQ9fIknKmXHecIomO_HhEk5Ot15LW8AW8cvsKb1Mwk6IGu1ZMSy-hD5w45kbWOcXG1bHveEYmA4k73nCo9Pzx7muPsSD7z8adsfkHQkf2dFc-YDzRSfziu21jO9alrmUPC2UbgvjZy8EZFj2yUzQfKIjYi04NmMzMjkwZDEwNTgiLCJvaWQiOiJlNDU3Nzc4NC1lMGE0LTQyZmYtODQ2Ni1iZjE3YWZiNmI1MmMiLCJzdWIiOiJDbGllbnQ6OmVlYjNlZDE1LTAwtNfKsDn4D9sCIw-97WO6Lf77ENPNu6Vgyl8d4j210kYMqcu8sGvAcpsE-_WVlAyiEi5ZhLMi_5EMcE9gK3h68109yjsceKvM0IxZw3WCnK2-2pMkiCmM27K92w6h2WIQ9XNbo4ibqYtFhOWPcmBZH9LOSOIWlQcwA=="
    }
}

The field token now contains an Access Token that will remain valide for the next 7,200 seconds (2 hours).

Use a generated Access Token

Once generated, you will have to pass the Access Token to all the other queries you may want to perform. This is done by adding the following Header to your requests:

--header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Example:

curl --location --request GET 'https://api-v2.musimap.io/lexicology/tags' \
--header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'