ArangoDB v3.12 is under development and not released yet. This documentation is not final and potentially incomplete.

HTTP interface for user management

The HTTP API for user management lets you create, modify, delete, and list ArangoDB user accounts, as well as grant and revoke permissions for databases and collections

The interface provides the means to manage database system users. All users managed through this interface are stored in the protected _users system collection.

You should never manipulate the _users collection directly. The specialized endpoints intentionally have limited functionality compared to the regular Document API.

See Managing Users for details and note that using wildcard database and collection access levels is discouraged.

User management operations are not included in ArangoDB’s replication.

Manage users

Create a user

post /_api/user
Create a new user. You need server access level Administrate in order to execute this REST call.
Request Body application/json
  • An optional flag that specifies whether the user is active. If not specified, this will default to true.

  • A JSON object with extra user information. It is used by the web interface to store graph viewer settings and saved queries. Should not be set or modified by end users, as custom attributes will not be preserved.

  • The user password as a string. If not specified, it will default to an empty string.

  • The name of the user as a string. This is mandatory.

Responses
  • Returned if the user can be added by the server

  • If the JSON representation is malformed or mandatory data is missing from the request.

  • Returned if you have No access database access level to the _system database.

  • Returned if you have No access server access level.

  • Returned if a user with the same name already exists.

Examples

curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/user
{
  "user": "admin@example",
  "passwd": "secure"
}
Show output

Replace a user

put /_api/user/{user}
Replaces the data of an existing user. You need server access level Administrate in order to execute this REST call. Additionally, users can change their own data.
Path Parameters
  • The name of the user.

Query Parameters
    HTTP Headers
      Request Body application/json
      • An optional flag that specifies whether the user is active. If not specified, this will default to true.

      • A JSON object with extra user information. It is used by the web interface to store graph viewer settings and saved queries. Should not be set or modified by end users, as custom attributes will not be preserved.

      • The user password as a string. If not specified, it will default to an empty string.

      Responses
      • Is returned if the user data can be replaced by the server.

      • The JSON representation is malformed or mandatory data is missing from the request

      • Returned if you have No access database access level to the _system database.

      • Returned if you have No access server access level.

      • The specified user does not exist

      Examples

      curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/user/admin@myapp
      {
        "passwd": "secure"
      }
      Show output

      Update a user

      patch /_api/user/{user}
      Partially modifies the data of an existing user. You need server access level Administrate in order to execute this REST call. Additionally, users can change their own data.
      Path Parameters
      • The name of the user.

      Query Parameters
        HTTP Headers
          Request Body application/json
          • An optional flag that specifies whether the user is active.

          • A JSON object with extra user information. It is used by the web interface to store graph viewer settings and saved queries. Should not be set or modified by end users, as custom attributes will not be preserved.

          • The user password as a string.

          Responses
          • Is returned if the user data can be replaced by the server.

          • The JSON representation is malformed or mandatory data is missing from the request.

          • Returned if you have No access database access level to the _system database.

          • Returned if you have No access server access level.

          • The specified user does not exist

          Examples

          curl -X PATCH --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/user/admin@myapp
          {
            "passwd": "secure"
          }
          Show output

          Remove a user

          delete /_api/user/{user}

          Removes an existing user, identified by user.

          You need Administrate permissions for the server access level in order to execute this REST call.

          Path Parameters
          • The name of the user

          Query Parameters
            HTTP Headers
              Responses
              • Is returned if the user was removed by the server

              • Returned if you have No access database access level to the _system database.

              • Returned if you have No access server access level.

              • The specified user does not exist

              Examples

              curl -X DELETE --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/user/userToDelete@myapp
              {}
              Show output

              Get a user

              get /_api/user/{user}
              Fetches data about the specified user. You can fetch information about yourself or you need the Administrate server access level in order to execute this REST call.
              Path Parameters
              • The name of the user

              Query Parameters
                HTTP Headers
                  Responses
                  • The user was found.

                  • Returned if you have No access database access level to the _system database.

                  • Returned if you have No access server access level.

                  • The user with the specified name does not exist.

                  Examples

                  curl --header 'accept: application/json' --dump - http://localhost:8529/_api/user/admin@myapp
                  Show output

                  List available users

                  get /_api/user/

                  Fetches data about all users. You need the Administrate server access level in order to execute this REST call. Otherwise, you will only get information about yourself.

                  The call will return a JSON object with at least the following attributes on success:

                  • user: The name of the user as a string.
                  • active: An optional flag that specifies whether the user is active.
                  • extra: A JSON object with extra user information. It is used by the web interface to store graph viewer settings and saved queries.
                  Responses
                  • The users that were found.

                  • Returned if you have No access database access level to the _system database.

                  • Returned if you have No access server access level.

                  Examples

                  curl --header 'accept: application/json' --dump - http://localhost:8529/_api/user
                  Show output

                  Manage permissions

                  Set a user’s database access level

                  put /_api/user/{user}/database/{dbname}
                  Sets the database access levels for the database dbname of user user. You need the Administrate server access level in order to execute this REST call.
                  Path Parameters
                  • The name of the user.

                  • The name of the database.

                  Query Parameters
                    HTTP Headers
                      Request Body application/json
                        • Use “rw” to set the database access level to Administrate.
                        • Use “ro” to set the database access level to Access.
                        • Use “none” to set the database access level to No access.

                      Responses
                      • Returned if the access level was changed successfully.

                      • If the JSON representation is malformed or mandatory data is missing from the request.

                      • Returned if you have No access database access level to the _system database.

                      • Returned if you have No access server access level.

                      Examples

                      curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/user/admin@myapp/database/_system
                      {
                        "grant": "rw"
                      }
                      Show output

                      Set a user’s collection access level

                      put /_api/user/{user}/database/{dbname}/{collection}
                      Sets the collection access level for the collection in the database dbname for user user. You need the Administrate server access level in order to execute this REST call.
                      Path Parameters
                      • The name of the user.

                      • The name of the database.

                      • The name of the collection.

                      Query Parameters
                        HTTP Headers
                          Request Body application/json
                          • Use “rw” to set the collection level access to Read/Write.

                            Use “ro” to set the collection level access to Read Only.

                            Use “none” to set the collection level access to No access.

                          Responses
                          • Returned if the access permissions were changed successfully.

                          • If the JSON representation is malformed or mandatory data is missing from the request.

                          • Returned if you have No access database access level to the _system database.

                          • Returned if you have No access server access level.

                          Examples

                          curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/user/admin@myapp/database/_system/reports
                          {
                            "grant": "rw"
                          }
                          Show output

                          Clear a user’s database access level

                          delete /_api/user/{user}/database/{dbname}

                          Clears the database access level for the database dbname of user user. As consequence, the default database access level is used. If there is no defined default database access level, it defaults to No access.

                          You need write permissions (Administrate access level) for the _system database in order to execute this REST call.

                          Path Parameters
                          • The name of the user.

                          • The name of the database.

                          Query Parameters
                            HTTP Headers
                              Responses
                              • Returned if the access permissions were changed successfully.

                              • If the JSON representation is malformed or mandatory data is missing from the request.

                              Examples

                              curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/user/admin@myapp/database/_system
                              Show output

                              Clear a user’s collection access level

                              delete /_api/user/{user}/database/{dbname}/{collection}

                              Clears the collection access level for the collection collection in the database dbname of user user. As consequence, the default collection access level is used. If there is no defined default collection access level, it defaults to No access.

                              You need write permissions (Administrate access level) for the _system database in order to execute this REST call.

                              Path Parameters
                              • The name of the user.

                              • The name of the database.

                              • The name of the collection.

                              Query Parameters
                                HTTP Headers
                                  Responses
                                  • Returned if the access permissions were changed successfully.

                                  • If there was an error

                                  Examples

                                  curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/user/admin@myapp/database/_system/reports
                                  Show output

                                  List a user’s accessible databases

                                  get /_api/user/{user}/database/

                                  Fetch the list of databases available to the specified user.

                                  You need Administrate permissions for the server access level in order to execute this REST call.

                                  The call will return a JSON object with the per-database access privileges for the specified user. The result object will contain the databases names as object keys, and the associated privileges for the database as values.

                                  In case you specified full, the result will contain the permissions for the databases as well as the permissions for the collections.

                                  Path Parameters
                                  • The name of the user for which you want to query the databases.

                                  Query Parameters
                                  • Return the full set of access levels for all databases and all collections.

                                  HTTP Headers
                                    Responses
                                    • Returned if the list of available databases can be returned.

                                    • If the access privileges are not right etc.

                                    • Returned if you have No access database access level to the _system database.

                                    • Returned if you have No access server access level.

                                    Examples

                                    curl --header 'accept: application/json' --dump - http://localhost:8529/_api/user/anotherAdmin@secapp/database/
                                    Show output

                                    With the full response format:

                                    curl --header 'accept: application/json' --dump - http://localhost:8529/_api/user/anotherAdmin@secapp/database?full=true
                                    Show output

                                    Get a user’s database access level

                                    get /_api/user/{user}/database/{dbname}
                                    Fetch the database access level for a specific database
                                    Path Parameters
                                    • The name of the user for which you want to query the databases.

                                    • The name of the database to query

                                    Query Parameters
                                      HTTP Headers
                                        Responses
                                        • Returned if the access level can be returned

                                        • If the access privileges are not right etc.

                                        • Returned if you have No access database access level to the _system database.

                                        • Returned if you have No access server access level.

                                        Examples

                                        curl --header 'accept: application/json' --dump - http://localhost:8529/_api/user/anotherAdmin@secapp/database/_system
                                        Show output

                                        Get a user’s collection access level

                                        get /_api/user/{user}/database/{dbname}/{collection}
                                        Returns the collection access level for a specific collection
                                        Path Parameters
                                        • The name of the user for which you want to query the databases.

                                        • The name of the database to query

                                        • The name of the collection

                                        Query Parameters
                                          HTTP Headers
                                            Responses
                                            • Returned if the access level can be returned

                                            • If the access privileges are not right etc.

                                            • Returned if you have No access database access level to the _system database.

                                            • Returned if you have No access server access level.

                                            Examples

                                            curl --header 'accept: application/json' --dump - http://localhost:8529/_api/user/anotherAdmin@secapp/database/_system/_users
                                            Show output