Admin Users API

These endpoints will allow you to easily manage admin users. Base URI is /api/v1/users.

Admin User API response structure

If you request an admin user via API, you will receive an object with the following fields:

Field Description
id Admin user’s id
username Admin user’s name
email Admin user’s email
enabled Flag set if the user is enabled

If you request for more detailed data, you will receive an object with the following fields:

Field Description
id Admin user’s id
username Admin user’s name
email Admin user’s email
enabled Flag set if the user is enabled
usernameCanonical Username of the admin user in canonical form
emailCanonical Email of the admin user in canonical form
roles Roles of the admin user
firstName The admin user’s first name
lastName The admin user’s last name
localeCode Code of the language, which is used by the admin user

Note

Read more about User model in the component docs.

Creating an Admin User

To create a new admin user you will need to call the /api/v1/users/ endpoint with the POST method.

Definition

POST /api/v1/users/
Parameter Parameter type Description
Authorization header Token received during authentication
username request Admin user name
email request Admin user email
plainPassword request Admin user password
localeCode request Code of the language, which is used by the admin user

Example

To create a new admin user use the below method:

$ curl http://demo.sylius.org/api/v1/users/ \
    -H "Authorization: Bearer SampleToken" \
    -H "Content-Type: application/json" \
    -X POST \
    --data '
        {
            "username": "Balrog",
            "email": "teamEvil@middleearth.com",
            "plainPassword": "youShallNotPass",
            "localeCode": "en_US"
        }
    '

Exemplary Response

STATUS: 201 CREATED
{
    "id": 7,
    "username": "Balrog",
    "usernameCanonical": "barlog",
    "roles": [
        "ROLE_ADMINISTRATION_ACCESS"
    ],
    "email": "teamEvil@middleearth.com",
    "emailCanonical": "teamevil@middleearth.com",
    "enabled": false
}

Warning

If you try to create an admin user without username, email, password or locale’s code, you will receive a 400 Bad Request error, that will contain validation errors.

Example

$ curl http://demo.sylius.org/api/v1/users/ \
    -H "Authorization: Bearer SampleToken" \
    -H "Content-Type: application/json" \
   -X POST

Exemplary Response

STATUS: 400 Bad Request
{
    "code": 400,
    "message": "Validation Failed",
    "errors": {
        "children": {
            "username": {
                "errors": [
                    "Please enter your name."
                ]
            },
            "email": {
                "errors": [
                    "Please enter your email."
                ]
            },
            "plainPassword": {
                "errors": [
                    "Please enter your password."
                ]
            },
            "enabled": {},
            "firstName": {},
            "lastName": {},
            "localeCode": {
                "errors": [
                    "Please choose a locale."
                ]
            }
        }
    }
}

You can also create an admin user with additional (not required) fields:

Parameter Parameter type Description
enabled request Flag set if the user is enabled
firstName request The admin user’s first name
lastName request The admin user’s last name

Example

$ curl http://demo.sylius.org/api/v1/users/ \
    -H "Authorization: Bearer SampleToken" \
    -H "Content-Type: application/json" \
    -X POST \
    --data '
        {
            "firstName": "Balrog",
            "lastName": "of Morgoth",
            "username": "Balrog",
            "email": "teamEvil@middleearth.com",
            "plainPassword": "youShallNotPass",
            "localeCode": "en_US",
            "enabled": "true"
        }
    '

Exemplary Response

STATUS: 201 CREATED
{
    "id": 9,
    "username": "Balrog",
    "usernameCanonical": "barlog",
    "roles": [
        "ROLE_ADMINISTRATION_ACCESS"
    ],
    "email": "teamEvil@middleearth.com",
    "emailCanonical": "teamevil@middleearth.com",
    "enabled": true,
    "firstName": "Balrog",
    "lastName": "of Morgoth"
}

Getting a Single Admin User

To retrieve the details of an admin user you will need to call the /api/v1/users/{id} endpoint with the GET method.

Definition

GET /api/v1/users/{id}
Parameter Parameter type Description
Authorization header Token received during authentication
id url attribute Id of the admin user

Example

To see the details for the admin user with id = 9 use the below method:

$ curl http://demo.sylius.org/api/v1/users/9 \
    -H "Authorization: Bearer SampleToken" \
    -H "Accept: application/json"

Note

The 9 id is an exemplary value. Your value can be different. Check in the list of all admin users if you are not sure which id should be used.

Exemplary Response

STATUS: 200 OK
{
    "id": 9,
    "username": "Balrog",
    "usernameCanonical": "barlog",
    "roles": [
        "ROLE_ADMINISTRATION_ACCESS"
    ],
    "email": "teamEvil@middleearth.com",
    "emailCanonical": "teamevil@middleearth.com",
    "enabled": true,
    "firstName": "Balrog",
    "lastName": "of Morgoth"
}

Collection of Admin Users

To retrieve a paginated list of admin users you will need to call the /api/v1/users/ endpoint with the GET method.

Definition

GET /api/v1/users/
Parameter Parameter type Description
Authorization header Token received during authentication
limit query (optional) Number of items to display per page, by default = 10

To see the first page of all admin users use the below method:

Example

$ curl http://demo.sylius.org/api/v1/users/ \
    -H "Authorization: Bearer SampleToken" \
    -H "Accept: application/json"

Exemplary Response

STATUS: 200 OK
{
    "page": 1,
    "limit": 4,
    "pages": 1,
    "total": 3,
    "_links": {
        "self": {
            "href": "\/api\/v1\/users\/?sorting%5Bcode%5D=desc&page=1&limit=4"
        },
        "first": {
            "href": "\/api\/v1\/users\/?sorting%5Bcode%5D=desc&page=1&limit=4"
        },
        "last": {
            "href": "\/api\/v1\/users\/?sorting%5Bcode%5D=desc&page=1&limit=4"
        }
    },
    "_embedded": {
        "items": [
            {
                "id": 5,
                "username": "sylius",
                "email": "sylius@example.com",
                "enabled": true
            },
            {
                "id": 6,
                "username": "api",
                "email": "api@example.com",
                "enabled": true
            },
            {
                "id": 9,
                "username": "Balrog",
                "email": "teamEvil@middleearth.com",
                "enabled": true
            }
        ]
    }
}

Updating an Admin User

To fully update an admin user you will need to call the /api/v1/users/{id} endpoint with the PUT method.

Definition

PUT /api/v1/users/{id}
Parameter Parameter type Description
Authorization header Token received during authentication
id url attribute Id of the admin user
username request Admin user name
email request Admin user email
plainPassword request Admin user password
localeCode request Code of the language, which is used by the admin user

Example

To fully update the admin user with id = 9 use the below method:
$ curl http://demo.sylius.org/api/v1/users/9 \
    -H "Authorization: Bearer SampleToken" \
    -H "Content-Type: application/json" \
    -X PUT \
    --data '
        {
            "firstName": "Gollum",
            "lastName": "Gollum!",
            "username": "Smeagol",
            "email": "smeagol@middleearth.com",
            "plainPassword": "myPrecious",
            "localeCode": "en_US"
        }
'

Exemplary Response

STATUS: 204 No Content

If you try to perform a full admin user update without all the required fields specified, you will receive a 400 Bad Request error.

Example

$ curl http://demo.sylius.org/api/v1/users/9 \
    -H "Authorization: Bearer SampleToken" \
    -H "Content-Type: application/json" \
    -X PUT

Exemplary Response

STATUS: 400 Bad Request
{
    "code": 400,
    "message": "Validation Failed",
    "errors": {
        "children": {
            "username": {
                "errors": [
                    "Please enter your name."
                ]
            },
            "email": {
                "errors": [
                    "Please enter your email."
                ]
            },
            "plainPassword": {},
            "enabled": {},
            "firstName": {},
            "lastName": {},
            "localeCode": {
                "errors": [
                    "Please choose a locale."
                ]
            }
        }
    }
}

To update an admin user partially you will need to call the /api/v1/users/{id} endpoint with the PATCH method.

Definition

PATCH /api/v1/users/{id}
Parameter Parameter type Description
Authorization header Token received during authentication
id url attribute Id of the admin user

Example

To partially update the admin user with id = 9 use the below method:

$ curl http://demo.sylius.org/api/v1/users/9 \
    -H "Authorization: Bearer SampleToken" \
    -H "Content-Type: application/json" \
    -X PATCH \
    --data '
        {
            "email": "smeagol@ring.com"
        }
    '

Exemplary Response

STATUS: 204 No Content

Deleting an Admin User

To delete an admin user you will need to call the /api/v1/users/{id} endpoint with the DELETE method.

Definition

DELETE /api/v1/users/{id}
Parameter Parameter type Description
Authorization header Token received during authentication
id url attribute Id of the admin user

Example

To delete the admin user with id = 9 use the below method:

$ curl http://demo.sylius.org/api/v1/users/9 \
    -H "Authorization: Bearer SampleToken" \
    -H "Accept: application/json" \
    -X DELETE

Exemplary Response

STATUS: 204 No Content

Warning

If you try to delete the admin user which is currently logged in, you will receive a 422 Unprocessable Entity error.

Example

$ curl http://demo.sylius.org/api/v1/users/6 \
    -H "Authorization: Bearer SampleToken" \
    -H "Accept: application/json" \
    -X DELETE

Exemplary Response

STATUS: 422 Unprocessable Entity
{
    "code": 422,
    "message": "Cannot remove currently logged in user."
}