Want to manage the access to the web API?

These simple steps will guide you and at the end, you will be able to grant access to the API to Peter, your favorite integrator!

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 manage any access to this PIM.


You are the administrator of the Akeneo PIM

You will need to have the rights to administrate the roles and users inside the PIM, so if you are the PIM administrator, it should be ok.


Peter, your favorite connector developer, is declared as a user in Akeneo PIM

Peter wants to develop a new connector for your Akeneo PIM and this conector will be doing requests via the Web API.

If not already done, create a new user named Peter in Akeneo PIM.

1

Create a Web API dedicated role

Log in as administrator in your PIM. In the System menu, select the User management menu, then click on the Role entry. From here, you should be able to create a role, click on Create role.

Once in the role form, give a name to the role you are creating, Whole API access for instance.

Then go to the Web API Permissions tab and activate the access to the Web API by clicking on Overall Web API access.

To finish, save your role by clicking on the Save button.

Great! You now have a role ready to access to the Web API. Let's go to the next step!

2

Give to Peter the role that allows him to access to the Web API

So now you have your role dedicated to the access of the Web API, you can give this role to a set of users. In the form of this role, got to the Users tab, select the users for which you want to give the access. Below, for example, we give to our developer Peter the Whole API access role.

3

Generate an OAuth client id and secret

Having a user with a role giving access to the Web API is not enough to make requests via the Web API. Peter will ask you for OAuth client id and secret so as he can be authenticated.

There are 2 ways to generate client ids and secrets.

With the PIM UI

Go to the System menu of your PIM and select the API connections entry.

From here, you can click on the Create button. Give a name to the connection you are about to create and confirrm. The PIM will then automatically create credentials for you, that you will find in the API connections grid.

This feature is only available in the PIM 2.0. If you are trying to use the API on a 1.7 PIM, please have a look to the second method below.

With a command line

Alternatively, you can create the client id and secret with a single command line directly on the PIM server.

With the 2.0 version

php bin/console pim:oauth-server:create-client my-customer-account \
    --grant_type="password" \
    --grant_type="refresh_token" \
    --env=prod
                                        

With the 1.7 version

php app/console pim:oauth-server:create-client \
    --label="my-customer-account"
    --grant_type="password" \
    --grant_type="refresh_token" \
    --env=prod
                                        

You will get something like:

A new client has been added:
client_id: 4gm4rnoizp8gskgkk080ssoo80040g44ksowwgw844k44sc00s
secret: 5dyvo1z6y34so4ogkgksw88ookoows00cgoc488kcs8wk4c40s
label: my-customer-account
                                        

Give by any mean of your choice these credentials to Peter. And that's it! Thanks to it, he will be able to finally access the API. Take a look to the Developer Getting started to know how.

To revoke the access, you just have to revoke it from the API connections screen (in 2.0) or run a single command line (in 1.7). To have more details, take a look at the Security section of the documention.

That's it! Peter is now ready to build amazing tools for your Akeneo PIM!

If you want to know more about managing the access to the web API, don't hesitate to


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