#Authentication

For security reasons, to access the REST API, you will need to be authenticated. To authenticate your REST API calls, the PIM will provide you a pair of client ID and secret. See here to discover how.

Client IDs allow two things:

• to ask for a token for a specific API user,
• to refresh an expired token.

This means that you will also need to create an API user in order to get this token.

Once you get its username and password, together with the client ID and the secret, you will eventually be able to generate a token for the REST API. This is the key to finally access the REST API. See here for more details.

#Client ID/secret generation

Follow this process to generate your “Client ID/secret”:

1. Log into your favorite PIM.
2. Go to the Connect/Connection settings menu.
3. Click on Create.
4. Input a label for your connection, ERP for example.
5. Select a type flow. Don't know what it is? More info here.
6. Click on Save.

Congrats! You officially created your very first connection to the PIM. 🎉

You can now find the client ID and secret in the Credentials section of the connection you've just created.

Not comfortable with the Connection notion? We explain everything right here!

#API user creation

You now have a client ID and a secret. But the request to get this token needs a username and a password.

This username and password are automatically generated whenever you create a connection in the UI. Depending on the version you use, navigate to the Connect/Connection settings menu, click on your connection and find your username and password in the Credentials section.

You may need to regenerate a password if you haven't saved it anywhere. Indeed, for security reasons, the PIM can only show it to you once, after the connection is created. There is a Regenerate button close to the hidden password if needed. 😉

#Token generation

You now have a client ID, a secret, a username and a password. The last information needed to use the REST API is the token.

First, you will have to encode the client ID and the secret, in base64, with a : in between.

client_id:secret
    4gm4rnoizp8gskgkk080ssoo80040g44ksowwgw844k44sc00s:5dyvo1z6y34so4ogkgksw88ookoows00cgoc488kcs8wk4c40s
    
    base64 encoded
    NGdtNHJub2l6cDhnc2tna2swODBzc29vODAwNDBnNDRrc293d2d3ODQ0azQ0c2MwMHM6NWR5dm8xejZ5MzRzbzRvZ2tna3N3ODhvb2tvb3dzMDBjZ29jNDg4a2NzOHdrNGM0MHM=
    

To get a valid token, the client application must send the following request:

curl -X POST http://your-host/api/oauth/v1/token \
        -H "Content-Type: application/json" \
        -H "Authorization: Basic YOUR_BASE_64_CLIENT_ID_AND_SECRET" \
        -d '{
            "grant_type": "password",
            "username": "your_API_username",
            "password": "its_password"
        }'
    

#Example

Request

curl -X POST http://my-favorite-pim.com/api/oauth/v1/token \
        -H "Content-Type: application/json" \
        -H "Authorization: Basic NGdtNHJub2l6cDhnc2tna2swODBzc29vODAwNDBnNDRrc293d2d3ODQ0azQ0c2MwMHM6NWR5dm8xejZ5MzRzbzRvZ2tna3N3ODhvb2tvb3dzMDBjZ29jNDg4a2NzOHdrNGM0MHM=" \
        -d '{
            "grant_type": "password",
            "username": "myERPuser",
            "password": "64bngr78"
        }'
    

Response

HTTP/1.1 200 OK
    
    {
        "access_token": "NzFiYTM4ZTEwMjcwZTcyZWIzZTA0NmY3NjE3MTIyMjM1Y2NlMmNlNWEyMTAzY2UzYmY0YWIxYmUzNTkyMDcyNQ",
        "expires_in": 3600,
        "token_type": "bearer",
        "scope": null,
        "refresh_token": "MDk2ZmIwODBkYmE3YjNjZWQ4ZTk2NTk2N2JmNjkyZDQ4NzA3YzhiZDQzMjJjODI5MmQ4ZmYxZjlkZmU1ZDNkMQ"
    }
    

Detail of the information given in the response:

• access_token must be included in every request to the REST API for the client application to be authorized (see the example below).
• expires_in is the token lifespan (in seconds). By default, it lasts 1 hour.
• refresh_token is a special token used only to refresh your access_token after it expired.

#Access a resource

Use the token that you just got for every request to the REST API.

#Example

curl https://demo.akeneo.com/api/rest/v1/categories \
        -H "Authorization: Bearer NzFiYTM4ZTEwMjcwZTcyZWIzZTA0NmY3NjE3MTIyMjM1Y2NlMmNlNWEyMTAzY2UzYmY0YWIxYmUzNTkyMDcyNQ"
    

#Refresh an expired token

For security reasons, access tokens have a certain lifespan. A client application using an expired token will be unable to request the REST API.

After a token has expired, the client application can ask for a new token by calling:

curl -X POST http://your-host/api/oauth/v1/token \
        -H "Content-Type: application/json" \
        -H "Authorization: Basic YOUR_BASE_64_CLIENT_ID_AND_SECRET" \
        -d '{
            "refresh_token" : "REFRESH_TOKEN",
            "grant_type": "refresh_token"
        }'
    

#Example

Request

curl --location --request POST 'http://my-favorite-pim.com/api/oauth/v1/token' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Basic M18xc3duZzU0ZHY2ODB3MG84Z2N3Y3d3ODRzd2tvYzA0NG9jc2c0b2N3azRjYzAwY2swdzozc3VhaHhlODhsaWNvdzAwZzBvODBnY2NnZ2d3OGNza2c0d2NvOHdvb293dzQ4ODBzbw==' \
    -d '{
        "refresh_token" : "OTI5MDE4ZjBiNjUyNWEyOTA5ZWQxNjE0ZDJiZTAzZTIwZjQ5ZDJmMDlhYzk4OTdjNzgzMTVkZDlmNTlmZjY3OQ",
        "grant_type": "refresh_token"
     }'
    

Response

HTTP/1.1 200 OK
    
    {
      "access_token": "MjkxYjM0ZGU0OGQzN2MzNmRmOGFkMzgxODdhMDZiNmE1MTI2ZDJmYmM5MTBhZWFiMGY0ZjE3YzJhOTJkOGRlZA",
      "expires_in": 3600,
      "token_type": "bearer",
      "scope": null,
      "refresh_token": "MTU2OWI5NGYwZTU2MThmMjE3MzRmYmIyMjlmYzU5Zjc3ZDhlM2E5YzQyMmIyMDVhOGY2OWQ3MTM0MTMzNmZlYw"
    }
    

The response is the same as when asking for the initial token, except that it contains a new access_token and a new refresh_token. You can then use this access_token for every REST API request you do within an hour.