New to our API?

These simple steps will guide you and at the end, you will be able to send your first request!

Prerequisites

An Akeneo PIM is already installed

This can seems pretty obvious. But yeah! You will need a PIM already installed if you want to make request on PIM data.

And of course, you also have to make sure that you can access it from where you are requesting.


You are in contact with the administrator of the Akeneo PIM

The Web API on each PIM installation can be restricted by its administrator. So you will have to make sure that you are in contact with him so that you can ask to grant you the access to the PIM data through the API.

If you are yourself the PIM administrator of the installed PIM on which you want to make requests via the API, that's ok. But before going further on the next steps, we advise you to follow the Getting started dedicated to the PIM admin first. Here you go!


You are a user in the Akeneo PIM

To access the Web API, you will have to be logged in in the system as a precise user. So make sure that you have a username and a password that corresponds to a PIM user of the PIM on which you want to make a request.

1

Ask for your OAuth client id and secret

To be authenticated when using the API, you will need to get a client id and a secret.

The PIM administrator is responsible for giving these credentials. Ask for it.

For your interest, the client id and the secret sould have the following form:

Client id
3e2iqilq2ygwk0ccgogkcwco8oosckkkk4gkoc0k4s8s044wss
Secret
44ectenmudus8g88w4wkws84044ckw0k4w4kg0sokoss84oko8

2

Get a token

So now you have your client id and secret, you are ready to get a token.

Concatenate your client id and secret with a : in between. For example, with the client id and secret given as example in step 1, this will give:

3e2iqilq2ygwk0ccgogkcwco8oosckkkk4gkoc0k4s8s044wss:44ectenmudus8g88w4wkws84044ckw0k4w4kg0sokoss84oko8

Then encode this string in base 64. There are utilities functions in every languages to do so and even websites, like this one.

You can also use the terminal to get the base64 encoded string:

echo -n 3e2iqilq2ygwk0ccgogkcwco8oosckkkk4gkoc0k4s8s044wss:44ectenmudus8g88w4wkws84044ckw0k4w4kg0sokoss84oko8 | base64

You will get:

M2UyaXFpbHEyeWd3azBjY2dvZ2tjd2NvOG9vc2Nra2trNGdrb2MwazRzOHMwNDR3c3M6NDRlY3Rlbm11ZHVzOGc4OHc0d2t3czg0MDQ0Y2t3MGs0dzRrZzBzb2tvc3M4NG9rbzg=

Then ask for a token by posting a request on the authentication URI specially crafted for this purpose: where-your-PIM-is-hosted/api/oauth/v1/token. Set the base64 encoded string as the Authorization header. The body of the request should be a JSON containing your username and password. Make sure that this username/password corresponds to your PIM user account on the PIM instance you want to make requests via the API. Below is an example of the request.

POST /api/oauth/v1/token HTTP/1.1
Host: where-your-PIM-is-hosted
Content-Type: application/json
Authorization: Basic M2UyaXFpbHEyeWd3azBjY2dvZ2tjd2NvOG9vc2Nra2trNGdrb2MwazRzOHMwNDR3c3M6NDRlY3Rlbm11ZHVzOGc4OHc0d2t3czg0MDQ0Y2t3MGs0dzRrZzBzb2tvc3M4NG9rbzg=

{
  "grant_type": "password",
  "username": "yourusername",
  "password": "yourpassword"
}


                                        

The PIM should answer with a 200 status and a JSON in the body response that will have this format:

{
    "access_token": "NzFiYTM4ZTEwMjcwZTcyZWIzZTA0NmY3NjE3MTIyMjM1Y2NlMmNlNWEyMTAzY2UzYmY0YWIxYmUzNTkyMDcyNQ",
    "expires_in": 3600,
    "token_type": "bearer",
    "scope": null,
    "refresh_token": "MDk2ZmIwODBkYmE3YjNjZWQ4ZTk2NTk2N2JmNjkyZDQ4NzA3YzhiZDQzMjJjODI5MmQ4ZmYxZjlkZmU1ZDNkMQ"
}

                                        

That's it! You just got your token. It's the string in the access_token property.

This token can be used during 1 hour. Then you will have to refresh it. Browse the dedicated documentation for more info.

3

Make your first request

Once you get your token, you just have to give it as an Authorization header of every request you make through the API.

For example, say you want to get the product with the identifier my_product, you will use the following the request:

GET api/rest/v1/products/my_product HTTP/1.1
Host: where-your-PIM-is-hosted
Content-Type: application/json
Authorization: Bearer NzFiYTM4ZTEwMjcwZTcyZWIzZTA0NmY3NjE3MTIyMjM1Y2NlMmNlNWEyMTAzY2UzYmY0YWIxYmUzNTkyMDcyNQ
                                        
                                        
Don't forget to mention the keyword Bearer before the token in the Authorization header.

If everything goes well, you will receive a 200 response with a body that looks like this:

{
  "identifier": "myproduct",
  "family": null,
  "groups": ["group_code_1", "group_code_3"],
  "variant_group": null,
  "categories": ["category_code_1"],
  "values": {
    "attribute_code_1":[
      {
        "locale": null,
        "scope": null,
        "data": 10
      }
    ]
  },
  "associations": {
    "pack": {
      "groups": [],
      "products": ["product_identifier_1","product_identifier_2"]
     },
     "x_sell": {
       "groups": [],
       "products": []
     }
  }
}

                                        

Well, this is your product. You made it, you made your first request!

If you experienced any error, please check the troubleshooting guide.

That's it! You are now ready to build amazing tools!

Start building by


Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!