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.
Request Body application/json object
active
boolean
An optional flag that specifies whether the user is active. If not
specified, this will default to true.
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. If not specified, it will default 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' <<'EOF'
{
"user": "admin@example",
"passwd": "secure"
}
EOF
Show outputHTTP/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. 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
Request Body application/json object
active
boolean
An optional flag that specifies whether the user is active. If not
specified, this will default to true.
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. If not specified, it will default 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' <<'EOF'
{
"passwd": "secure"
}
EOF
Show outputHTTP/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
Request Body application/json object
active
boolean
An optional flag that specifies whether the user is active.
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' <<'EOF'
{
"passwd": "secure"
}
EOF
Show outputHTTP/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
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' <<'EOF'
{}
EOF
Show outputHTTP/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
Responses
200
OK
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 outputHTTP/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: 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.
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.
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 outputHTTP/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
dbname*
string
The name of the database to set the access level for.
Request Body application/json object
grant*
string
- 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
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' <<'EOF'
{
"grant": "rw"
}
EOF
Show outputHTTP/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
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.
Request Body application/json object
grant*
string
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
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' <<'EOF'
{
"grant": "rw"
}
EOF
Show outputHTTP/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
dbname*
string
The name of the database to clear the access level for.
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 outputHTTP/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
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.
Responses
202
Accepted
Returned if the access permissions were changed successfully.
400
Bad Request
Examples
curl -X DELETE --header 'accept: application/json' --dump - 'http://localhost:8529/_api/user/admin@myapp/database/_system/reports'
Show outputHTTP/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
Return the full set of access levels for all databases and all collections.
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 outputHTTP/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 outputHTTP/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" : {
"_statistics15" : "undefined",
"_appbundles" : "undefined",
"_graphs" : "undefined",
"demo" : "undefined",
"_statisticsRaw" : "undefined",
"animals" : "undefined",
"mycollection" : "undefined",
"ignore" : "undefined",
"_aqlfunctions" : "undefined",
"_frontend" : "undefined",
"_analyzers" : "undefined",
"_queues" : "undefined",
"_statistics" : "undefined",
"_users" : "undefined",
"_apps" : "undefined",
"_jobs" : "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.
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 outputHTTP/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.
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 outputHTTP/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"
}
