Akeneo User API
A user is a person who signs in to the PIM. Their roles define what they are allowed to do, and their user groups define which data they can access.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/akeneo:akeneo-user-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Akeneo API REFERENCE User API
version: 1.0.0
description: 'This is the reference documentation for the Akeneo PIM REST API.
It provides detailed information about the available endpoints, request and response formats, and authentication methods.
For more information, visit the Akeneo PIM documentation.'
license:
name: Open Software License 3.0
url: http://opensource.org/licenses/OSL-3.0
contact:
name: Akeneo Support
url: https://www.akeneo.com/support-help-center/
email: contact@akeneo.com
servers:
- url: '{your-pim-url}'
variables:
your-pim-url:
default: ''
description: 'Set the PIM url you want to target ex: https://my-pim.cloud.akeneo.com or https://localhost:8443'
tags:
- name: User
description: 'A user is a person who signs in to the PIM.
Their roles define what they are allowed to do, and their user groups define which data they can access.'
paths:
/api/rest/v1/users:
get:
operationId: get_users
x-visibility: public
summary: Get a list of users
description: 'This endpoint allows you to get a list of users.
Users are paginated and sorted by username. API and job users are not listed.'
tags:
- User
security:
- bearerToken: []
parameters:
- in: query
name: page
description: 'Specify which page of results to retrieve when using pagination.
It is useful for navigating through large datasets by breaking them into smaller, manageable pages.
See [Pagination](https://api.akeneo.com/documentation/pagination.html) section for more details.
'
required: false
schema:
type: integer
default: 1
example: 1
- in: query
name: limit
description: 'Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See [Pagination](https://api.akeneo.com/documentation/pagination.html) section for more details.
'
required: false
schema:
type: integer
default: 10
minimum: 1
maximum: 100
example: 100
- in: query
name: with_count
description: 'Return the count of items in the response.
Be careful with that, on a big catalog, it can decrease performance in a significant way.
It is useful for understanding the size of the dataset being returned, especially when dealing with large collections.
Use it judiciously to avoid performance issues.
'
required: false
schema:
type: boolean
default: false
example: true
- name: search
in: query
description: 'Filter users on their `roles` (role codes) or their `groups` (user group names).
Both filters only accept the `IN` operator. Several criteria are combined with AND.
'
required: false
schema:
type: string
examples:
getUsersByRole:
summary: Filter the users by their role
value: '{"roles":[{"operator":"IN","value":["ROLE_ADMINISTRATOR"]}]}'
getUsersByGroup:
summary: Filter the users by their user group
value: '{"groups":[{"operator":"IN","value":["IT support","Manager"]}]}'
responses:
'200':
description: 'Return users paginated.
The response is paginated and includes links to navigate through the pages.
'
content:
application/json:
schema:
title: Users
type: object
allOf:
- type: object
properties:
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
description: URI of the current page of resources
example: https://demo.akeneo.com/api/rest/v1/categories?page=2&limit=5
first:
type: object
properties:
href:
type: string
description: URI of the first page of resources
example: https://demo.akeneo.com/api/rest/v1/categories?page=1&limit=5
previous:
type: object
properties:
href:
type: string
description: URI of the previous page of resources
example: https://demo.akeneo.com/api/rest/v1/categories?page=1&limit=5
next:
type: object
properties:
href:
type: string
description: URI of the next page of resources
example: https://demo.akeneo.com/api/rest/v1/categories?page=3&limit=5
- type: object
properties:
current_page:
type: integer
description: Current page number
example: 1
items_count:
type: integer
description: Total number of items (only if `with_count` parameter is set to true)
example: 2
_embedded:
type: object
properties:
items:
type: array
items:
allOf:
- type: object
properties:
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
description: URI of the resource
example: https://demo.akeneo.com/api/rest/v1/users/7a5c1e1f-3a4b-4c8e-9d2f-6b1e8f0a2c3d
- type: object
properties:
uuid:
type: string
format: uuid
description: User UUID
x-immutable: true
example: 7a5c1e1f-3a4b-4c8e-9d2f-6b1e8f0a2c3d
email:
type: string
description: User email
example: julia@example.com
enabled:
type: boolean
description: Whether the user is enabled
example: true
first_name:
type:
- string
- 'null'
description: User first name
example: Julia
last_name:
type:
- string
- 'null'
description: User last name
example: Stark
roles:
type: array
description: Codes of the roles of the user, sorted by code
items:
type: string
example:
- ROLE_CATALOG_MANAGER
groups:
type: array
description: Names of the user groups of the user, sorted by name, the default "All" group excluded
items:
type: string
example:
- Manager
required:
- uuid
- email
- enabled
- first_name
- last_name
- roles
- groups
example:
_links:
self:
href: https://demo.akeneo.com/api/rest/v1/users?page=1&limit=10&with_count=true
first:
href: https://demo.akeneo.com/api/rest/v1/users?page=1&limit=10&with_count=true
current_page: 1
items_count: 2
_embedded:
items:
- _links:
self:
href: https://demo.akeneo.com/api/rest/v1/users/2f0b6a4c-8e1d-4b7a-9c3e-5d2a1f6e8b90
uuid: 2f0b6a4c-8e1d-4b7a-9c3e-5d2a1f6e8b90
email: admin@example.com
enabled: true
first_name: John
last_name: Doe
roles:
- ROLE_ADMINISTRATOR
groups:
- IT support
- _links:
self:
href: https://demo.akeneo.com/api/rest/v1/users/7a5c1e1f-3a4b-4c8e-9d2f-6b1e8f0a2c3d
uuid: 7a5c1e1f-3a4b-4c8e-9d2f-6b1e8f0a2c3d
email: julia@example.com
enabled: true
first_name: Julia
last_name: Stark
roles:
- ROLE_CATALOG_MANAGER
groups:
- Manager
'400':
description: 'This response indicates that the server cannot process the request due to a client error, such as malformed request syntax, invalid request message framing, or deceptive request routing.
It is typically used when the server cannot understand the request due to invalid JSON or other client-side issues.
'
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: HTTP status code
example: 401
message:
type: string
description: Message explaining the error
example: Full authentication is required to access this resource.
example:
code: 400
message: Invalid JSON message received
'401':
description: 'This response indicates that authentication is required to access the requested resource.
It can be caused by a missing or expired token, or if the provided credentials are invalid.
'
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: HTTP status code
example: 401
message:
type: string
description: Message explaining the error
example: Full authentication is required to access this resource.
example:
code: 401
message: Full authentication is required to access this resource.
'403':
description: 'This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
'
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: HTTP status code
example: 401
message:
type: string
description: Message explaining the error
example: Full authentication is required to access this resource.
example:
code: 403
message: Access forbidden. You are not allowed to list this entity.
'406':
description: 'This response indicates that the server cannot produce a response matching the list of acceptable values defined in the request''s `Accept` header.
It is typically used when the requested resource is not available in the requested format.
'
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: HTTP status code
example: 401
message:
type: string
description: Message explaining the error
example: Full authentication is required to access this resource.
example:
code: 406
message: xxx in `Accept` header is not valid. Only `application/json` is allowed.
'422':
description: 'This response indicates that the validation of the entity given in the body of the request failed.
It occurs when the server understands the request but cannot process it due to validation errors in the provided data.
'
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: HTTP status code
example: 422
message:
type: string
description: Message explaining the error
example: Validation failed.
errors:
type: array
description: A list of validation error messages (optional)
items:
type: object
properties:
property:
type: string
description: Name of the invalid property
message:
type: string
description: Human-readable error message
attribute:
type:
- string
- 'null'
description: Attribute code (if the error is on an attribute)
locale:
type:
- string
- 'null'
description: Locale code involved in the error, if any
scope:
type:
- string
- 'null'
description: Channel code involved in the error, if any
example:
- property: family
message: The tshirts family does not exist in your PIM.
_links:
type: object
properties:
documentation:
type: object
properties:
href:
type: string
example:
documentation:
href: http://api.akeneo.com/api-reference.html
example:
code: 422
message: Validation failed.
errors:
- property: family
message: The tshirts family does not exist in your PIM.
- property: categories
message: The "tvs_projectors" category does not exist.
- property: associations.SUBSTITUTION.groups
message: You should associate existing groups. The "promotion" group does not exist.
- property: values
message: The "description" attribute requires a channel.
attribute: description
locale: en_US
scope: null
- property: values
message: The "name" attribute requires a locale.
attribute: name
locale: null
scope: null
_links:
documentation:
href: http://api.akeneo.com/api-reference.html
/api/rest/v1/users/{uuid}:
get:
operationId: get_user_by_uuid
x-visibility: public
summary: Get a user
description: This endpoint allows you to get the information about a given user.
tags:
- User
security:
- bearerToken: []
parameters:
- in: path
name: uuid
description: 'This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the UUID is correctly formatted and corresponds to an existing entity in the system.
'
required: true
schema:
type: string
format: uuid
example: 123e4567-e89b-12d3-a456-426614174000
responses:
'200':
description: Returns the user
content:
application/json:
schema:
type: object
properties:
uuid:
type: string
format: uuid
description: User UUID
x-immutable: true
example: 7a5c1e1f-3a4b-4c8e-9d2f-6b1e8f0a2c3d
email:
type: string
description: User email
example: julia@example.com
enabled:
type: boolean
description: Whether the user is enabled
example: true
first_name:
type:
- string
- 'null'
description: User first name
example: Julia
last_name:
type:
- string
- 'null'
description: User last name
example: Stark
roles:
type: array
description: Codes of the roles of the user, sorted by code
items:
type: string
example:
- ROLE_CATALOG_MANAGER
groups:
type: array
description: Names of the user groups of the user, sorted by name, the default "All" group excluded
items:
type: string
example:
- Manager
required:
- uuid
- email
- enabled
- first_name
- last_name
- roles
- groups
example:
uuid: 7a5c1e1f-3a4b-4c8e-9d2f-6b1e8f0a2c3d
email: julia@example.com
enabled: true
first_name: Julia
last_name: Stark
roles:
- ROLE_CATALOG_MANAGER
groups:
- Manager
'401':
description: 'This response indicates that authentication is required to access the requested resource.
It can be caused by a missing or expired token, or if the provided credentials are invalid.
'
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: HTTP status code
example: 401
message:
type: string
description: Message explaining the error
example: Full authentication is required to access this resource.
example:
code: 401
message: Full authentication is required to access this resource.
'403':
description: 'This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process.
'
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: HTTP status code
example: 401
message:
type: string
description: Message explaining the error
example: Full authentication is required to access this resource.
example:
code: 403
message: Access forbidden. You are not allowed to list this entity.
'404':
description: 'This response indicates that the requested resource could not be found on the server.
It can occur when the resource code given in the URI does not correspond to any existing PIM resource.
'
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: HTTP status code
example: 401
message:
type: string
description: Message explaining the error
example: Full authentication is required to access this resource.
example:
code: 404
message: Resource `my_resource_code` does not exist.
'406':
description: 'This response indicates that the server cannot produce a response matching the list of acceptable values defined in the request''s `Accept` header.
It is typically used when the requested resource is not available in the requested format.
'
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: HTTP status code
example: 401
message:
type: string
description: Message explaining the error
example: Full authentication is required to access this resource.
example:
code: 406
message: xxx in `Accept` header is not valid. Only `application/json` is allowed.
components:
securitySchemes:
basicToken:
scheme: basic
type: http
description: 'HTTP Basic authentication using user credentials.
[More information here](https://api.akeneo.com/documentation/authentication.html)
'
bearerToken:
scheme: bearer
type: http
description: 'Bearer token obtained via the "Password Grant" flow.
This token authenticates a user, is valid for one hour, and can be refreshed using a refresh token.
[More information here](https://api.akeneo.com/documentation/authentication.html)
'
appToken:
scheme: bearer
type: http
description: 'Bearer token for Apps, obtained via the OAuth 2.0 flow.
This permanent token allows an application to make requests on behalf of a user.
[More information here](https://api.akeneo.com/apps/authentication-and-authorization.html)
'
x-provenance:
method: harvested
publisher: Akeneo
source: https://storage.googleapis.com/akecld-prd-pim-saas-shared-openapi-spec/openapi.yaml
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)