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.

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

  • user (string, required): The name of the user as a string. This is mandatory.

  • passwd (string, required): The user password as a string. If not specified, it will default to an empty string.

  • active (boolean, optional): An optional flag that specifies whether the user is active. If not specified, this will default to true.

  • extra (object, optional): 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.

Responses

HTTP 201: Returned if the user can be added by the server

HTTP 400: If the JSON representation is malformed or mandatory data is missing from the request.

HTTP 401: Returned if you have No access database access level to the _system database.

HTTP 403: Returned if you have No access server access level.

HTTP 409: Returned if a user with the same name already exists.

Examples

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

HTTP/1.1 201 Created
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 74
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

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

  • user (string, required): The name of the user.

Request Body

  • passwd (string, required): The user password as a string. If not specified, it will default to an empty string.

  • active (boolean, optional): An optional flag that specifies whether the user is active. If not specified, this will default to true.

  • extra (object, optional): 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.

Responses

HTTP 200: Is returned if the user data can be replaced by the server.

HTTP 400: The JSON representation is malformed or mandatory data is missing from the request

HTTP 401: Returned if you have No access database access level to the _system database.

HTTP 403: Returned if you have No access server access level.

HTTP 404: The specified user does not exist

Examples

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

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 72
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

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

  • user (string, required): The name of the user.

Request Body

  • passwd (string, required): The user password as a string.

  • active (boolean, optional): An optional flag that specifies whether the user is active.

  • extra (object, optional): 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.

Responses

HTTP 200: Is returned if the user data can be replaced by the server.

HTTP 400: The JSON representation is malformed or mandatory data is missing from the request.

HTTP 401: Returned if you have No access database access level to the _system database.

HTTP 403: Returned if you have No access server access level.

HTTP 404: The specified user does not exist

Examples

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

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 72
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

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

  • user (string, required): The name of the user

Responses

HTTP 202: Is returned if the user was removed by the server

HTTP 401: Returned if you have No access database access level to the _system database.

HTTP 403: Returned if you have No access server access level.

HTTP 404: The specified user does not exist

Examples

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

HTTP/1.1 202 Accepted
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 26
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

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

  • user (string, required): The name of the user

Responses

HTTP 200: The user was found.

HTTP 401: Returned if you have No access database access level to the _system database.

HTTP 403: Returned if you have No access server access level.

HTTP 404: The user with the specified name does not exist.

Examples

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

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 72
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

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

HTTP 200: The users that were found.

HTTP 401: Returned if you have No access database access level to the _system database.

HTTP 403: Returned if you have No access server access level.

Examples

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/user

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 164
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

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

  • user (string, required): The name of the user.

  • dbname (string, required): The name of the database.

Request Body

  • grant (string, required):
    • 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

HTTP 200: Returned if the access level was changed successfully.

HTTP 400: If the JSON representation is malformed or mandatory data is missing from the request.

HTTP 401: Returned if you have No access database access level to the _system database.

HTTP 403: Returned if you have No access server access level.

Examples

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

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 41
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

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

  • user (string, required): The name of the user.

  • dbname (string, required): The name of the database.

  • collection (string, required): The name of the collection.

Request Body

  • grant (string, required): 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

HTTP 200: Returned if the access permissions were changed successfully.

HTTP 400: If the JSON representation is malformed or mandatory data is missing from the request.

HTTP 401: Returned if you have No access database access level to the _system database.

HTTP 403: Returned if you have No access server access level.

Examples

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

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 49
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

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

  • user (string, required): The name of the user.

  • dbname (string, required): The name of the database.

Responses

HTTP 202: Returned if the access permissions were changed successfully.

HTTP 400: If the JSON representation is malformed or mandatory data is missing from the request.

Examples

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

HTTP/1.1 202 Accepted
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 26
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

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

  • user (string, required): The name of the user.

  • dbname (string, required): The name of the database.

  • collection (string, required): The name of the collection.

Responses

HTTP 202: Returned if the access permissions were changed successfully.

HTTP 400: If there was an error

Examples

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

HTTP/1.1 202 Accepted
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 26
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

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

  • user (string, required): The name of the user for which you want to query the databases.

Query Parameters

  • full (boolean, optional): Return the full set of access levels for all databases and all collections.

Responses

HTTP 200: Returned if the list of available databases can be returned.

HTTP 400: If the access privileges are not right etc.

HTTP 401: Returned if you have No access database access level to the _system database.

HTTP 403: Returned if you have No access server access level.

Examples

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

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 52
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

With the full response format:

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

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 487
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

Get a user’s database access level

GET /_api/user/{user}/database/{dbname}

Fetch the database access level for a specific database

Path Parameters

  • user (string, required): The name of the user for which you want to query the databases.

  • dbname (string, required): The name of the database to query

Responses

HTTP 200: Returned if the access level can be returned

HTTP 400: If the access privileges are not right etc.

HTTP 401: Returned if you have No access database access level to the _system database.

HTTP 403: Returned if you have No access server access level.

Examples

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

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 40
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

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

  • user (string, required): The name of the user for which you want to query the databases.

  • dbname (string, required): The name of the database to query

  • collection (string, required): The name of the collection

Responses

HTTP 200: Returned if the access level can be returned

HTTP 400: If the access privileges are not right etc.

HTTP 401: Returned if you have No access database access level to the _system database.

HTTP 403: Returned if you have No access server access level.

Examples

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

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 42
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body
❮  Authentication

© ArangoDB - Graph and Beyond