ArangoDB v3.13 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 /_db/{database-name}/_api/user

Create a new user. You need server access level Administrate in order to execute this REST call.

Path Parameters

database-name* string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database and administrate access to the _system database.

Query Parameters

HTTP Headers

Request Body application/json object

active boolean (default: true)
Whether the user account should be able to log in to the database system.
extra object
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.
passwd string (default: "")
The user password as a string. If not specified, it defaults to an empty string.
user* string
The name of the user as a string. This is mandatory.

Responses

201 Created
Returned if the user can be added by the server
400 Bad Request
If the JSON representation is malformed or mandatory data is missing from the request.
401 Unauthorized
Returned if you have No access database access level to the _system database.
403 Forbidden
Returned if you have No access server access level.
409 Conflict
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

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

{ 
  "user" : "admin@example", 
  "active" : true, 
  "extra" : { 
  }, 
  "code" : 201, 
  "error" : false 
}

Replace a user

PUT /_db/{database-name}/_api/user/{user}

Replaces the data of an existing user. This resets the user’s access levels for databases and collections. You need server access level Administrate in order to execute this REST call. Additionally, users can change their own data.

Path Parameters

database-name* string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database and administrate access to the _system database.
user* string
The name of the user.

Query Parameters

HTTP Headers

Request Body application/json object

active boolean (default: true)
Whether the user account should be able to log in to the database system.
extra object
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.
passwd string (default: "")
The user password as a string. If not specified, it defaults to an empty string.

Responses

200 OK
Is returned if the user data can be replaced by the server.
400 Bad Request
The JSON representation is malformed or mandatory data is missing from the request
401 Unauthorized
Returned if you have No access database access level to the _system database.
403 Forbidden
Returned if you have No access server access level.
404 Not Found
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

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

{ 
  "user" : "admin@myapp", 
  "active" : true, 
  "extra" : { 
  }, 
  "code" : 200, 
  "error" : false 
}

Update a user

PATCH /_db/{database-name}/_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

database-name* string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database and administrate access to the _system database.
user* string
The name of the user.

Query Parameters

HTTP Headers

Request Body application/json object

active boolean
Whether the user account should be able to log in to the database system.
extra object
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.
passwd string
The user password as a string.

Responses

200 OK
Is returned if the user data can be replaced by the server.
400 Bad Request
The JSON representation is malformed or mandatory data is missing from the request.
401 Unauthorized
Returned if you have No access database access level to the _system database.
403 Forbidden
Returned if you have No access server access level.
404 Not Found
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

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

{ 
  "user" : "admin@myapp", 
  "active" : true, 
  "extra" : { 
  }, 
  "code" : 200, 
  "error" : false 
}

Remove a user

DELETE /_db/{database-name}/_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

database-name* string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database and administrate access to the _system database.
user* string
The name of the user

Query Parameters

HTTP Headers

Responses

202 Accepted
Is returned if the user was removed by the server
401 Unauthorized
Returned if you have No access database access level to the _system database.
403 Forbidden
Returned if you have No access server access level.
404 Not Found
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

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

{ 
  "error" : false, 
  "code" : 202 
}

Get a user

GET /_db/{database-name}/_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

database-name* string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database and administrate access to the _system database.
user* string
The name of the user

Query Parameters

HTTP Headers

Responses

200 OK
The user was found.
401 Unauthorized
Returned if you have No access database access level to the _system database.
403 Forbidden
Returned if you have No access server access level.
404 Not Found
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

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

{ 
  "user" : "admin@myapp", 
  "active" : true, 
  "extra" : { 
  }, 
  "code" : 200, 
  "error" : false 
}

List available users

GET /_db/{database-name}/_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: Whether the user account is able to log in to the database system.
extra: A JSON object with extra user information. It is used by the web interface to store graph viewer settings and saved queries.

Path Parameters

database-name* string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database and administrate access to the _system database.

Query Parameters

HTTP Headers

Responses

200 OK
The users that were found.
401 Unauthorized
Returned if you have No access database access level to the _system database.
403 Forbidden
Returned if you have No access server access level.

Examples

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

Show output

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

{ 
  "error" : false, 
  "code" : 200, 
  "result" : [ 
    { 
      "user" : "tester", 
      "active" : false, 
      "extra" : { 
      } 
    }, 
    { 
      "user" : "admin", 
      "active" : true, 
      "extra" : { 
      } 
    }, 
    { 
      "user" : "root", 
      "active" : true, 
      "extra" : { 
      } 
    } 
  ] 
}

Manage permissions

Set a user’s database access level

PUT /_db/{database-name}/_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

database-name* string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database and administrate access to the _system database.
user* string
The name of the user.
dbname* string
The name of the database to set the access level for.

Query Parameters

HTTP Headers

Request Body application/json object

grant* string
Possible values: "rw", "ro", "none"
- "rw": Set the database access level to Administrate.
- "ro": Set the database access level to Access.
- "none": Set the database access level to No access.

Responses

200 OK
Returned if the access level was changed successfully.
400 Bad Request
If the JSON representation is malformed or mandatory data is missing from the request.
401 Unauthorized
Returned if you have No access database access level to the _system database.
403 Forbidden
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

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

{ 
  "_system" : "rw", 
  "code" : 200, 
  "error" : false 
}

Set a user’s collection access level

PUT /_db/{database-name}/_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

database-name* string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database and administrate access to the _system database.
user* string
The name of the user.
dbname* string
The name of the database to set the access level for.
collection* string
The name of the collection to set the access level for.

Query Parameters

HTTP Headers

Request Body application/json object

grant* string
Possible values: "rw", "ro", "none"
- "rw": Set the collection access level to Read/Write.
- "ro": Set the collection access level to Read Only.
- "none": Set the collection access level to No access.

Responses

200 OK
Returned if the access permissions were changed successfully.
400 Bad Request
If the JSON representation is malformed or mandatory data is missing from the request.
401 Unauthorized
Returned if you have No access database access level to the _system database.
403 Forbidden
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

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

{ 
  "_system/reports" : "rw", 
  "code" : 200, 
  "error" : false 
}

Clear a user’s database access level

DELETE /_db/{database-name}/_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

database-name* string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database and administrate access to the _system database.
user* string
The name of the user.
dbname* string
The name of the database to clear the access level for.

Query Parameters

HTTP Headers

Responses

202 Accepted
Returned if the access permissions were changed successfully.
400 Bad Request
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

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

{ 
  "error" : false, 
  "code" : 202 
}

Clear a user’s collection access level

DELETE /_db/{database-name}/_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

database-name* string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database and administrate access to the _system database.
user* string
The name of the user.
dbname* string
The name of the database to clear the access level for.
collection* string
The name of the collection to clear the access level for.

Query Parameters

HTTP Headers

Responses

202 Accepted
Returned if the access permissions were changed successfully.
400 Bad Request
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

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

{ 
  "error" : false, 
  "code" : 202 
}

List a user’s accessible databases

GET /_db/{database-name}/_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

database-name* string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database and administrate access to the _system database.
user* string
The name of the user for which you want to query the databases.

Query Parameters

full boolean (default: false)
Return the full set of access levels for all databases and all collections.

HTTP Headers

Responses

200 OK
Returned if the list of available databases can be returned.
400 Bad Request
If the access privileges are not right etc.
401 Unauthorized
Returned if you have No access database access level to the _system database.
403 Forbidden
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

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

{ 
  "error" : false, 
  "code" : 200, 
  "result" : { 
    "_system" : "rw" 
  } 
}

With the full response format:

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

Show output

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

{ 
  "error" : false, 
  "code" : 200, 
  "result" : { 
    "_system" : { 
      "permission" : "rw", 
      "collections" : { 
        "demo" : "undefined", 
        "_jobs" : "undefined", 
        "animals" : "undefined", 
        "_queues" : "undefined", 
        "_statistics" : "undefined", 
        "_aqlfunctions" : "undefined", 
        "_users" : "undefined", 
        "_frontend" : "undefined", 
        "_analyzers" : "undefined", 
        "_appbundles" : "undefined", 
        "_graphs" : "undefined", 
        "_apps" : "undefined", 
        "_statisticsRaw" : "undefined", 
        "mycollection" : "undefined", 
        "_statistics15" : "undefined", 
        "ignore" : "undefined", 
        "*" : "undefined" 
      } 
    }, 
    "*" : { 
      "permission" : "none" 
    } 
  } 
}

Get a user’s database access level

GET /_db/{database-name}/_api/user/{user}/database/{dbname}

Fetch the database access level for a specific database

Path Parameters

database-name* string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database and administrate access to the _system database.
user* string
The name of the user for which you want to query the databases.
dbname* string
The name of the database to query the access level of.

Query Parameters

HTTP Headers

Responses

200 OK
Returned if the access level can be returned
400 Bad Request
If the access privileges are not right etc.
401 Unauthorized
Returned if you have No access database access level to the _system database.
403 Forbidden
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

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

{ 
  "error" : false, 
  "code" : 200, 
  "result" : "rw" 
}

Get a user’s collection access level

GET /_db/{database-name}/_api/user/{user}/database/{dbname}/{collection}

Returns the collection access level for a specific collection

Path Parameters

database-name* string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database and administrate access to the _system database.
user* string
The name of the user for which you want to query the databases.
dbname* string
The name of the database to query the access level of.
collection* string
The name of the collection to query the access level of.

Query Parameters

HTTP Headers

Responses

200 OK
Returned if the access level can be returned
400 Bad Request
If the access privileges are not right etc.
401 Unauthorized
Returned if you have No access database access level to the _system database.
403 Forbidden
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

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

{ 
  "error" : false, 
  "code" : 200, 
  "result" : "none" 
}