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
    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
      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
        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
          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
            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
              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
                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
                  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.

                  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
                    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
                      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