HTTP Interface for User Management
This is an introduction to ArangoDB's HTTP interface for managing users.
The interface provides a simple means to add, update, and remove users. All users managed through this interface will be stored in the system collection _users. You should never manipulate the _users collection directly.
This specialized interface intentionally does not provide all functionality that is available in the regular document REST API.
Please note that user operations are not included in ArangoDB's replication.
Create User
Create a new user.
POST /_api/user
A json post document with these Properties is required:
- passwd: The user password as a string. If no password is specified, the empty
string will be used. If you pass the special value
ARANGODB_DEFAULT_ROOT_PASSWORD, the password will be set the value
stored in the environment variable
ARANGODB_DEFAULT_ROOT_PASSWORD
. This can be used to pass an instance variable into ArangoDB. For example, the instance identifier from Amazon. - active: An optional flag that specifies whether the user is active. If not specified, this will default to true
- user: The name of the user as a string. This is mandatory.
- extra: An optional JSON object with arbitrary extra data about the user.
Create a new user. This user will not have access to any database. You need permission to the _system database in order to execute this REST call.
Example:
shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/user <<EOF
{
"user" : "admin@example",
"passwd" : "secure"
}
EOF
HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
{
"user" : "admin@example",
"active" : true,
"extra" : {
},
"changePassword" : false,
"error" : false,
"code" : 201
}
Return Codes
- 201: Returned if the user can be added by the server
- 400: If the JSON representation is malformed or mandatory data is missing from the request.
Examples
shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/user <<EOF
{
"user" : "admin@example",
"passwd" : "secure"
}
EOF
HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
{
"user" : "admin@example",
"active" : true,
"extra" : {
},
"changePassword" : false,
"error" : false,
"code" : 201
}
shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/user <<EOF
{
"user" : "admin@example",
"passwd" : "secure"
}
EOF
HTTP/1.1 201 Created
content-type: application/json; charset=utf-8
Grant or revoke database access
Grant or revoke access to a database.
PUT /_api/user/{user}/database/{dbname}
A json post document with these Properties is required:
- grant: Use "rw" to grant access right and "none" to revoke.
Grants or revokes access to the database dbname for user user. You need permission to the _system database in order to execute this REST call.
Example:
shell> curl -X PUT --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; charset=utf-8
{
"_system" : "rw",
"error" : false,
"code" : 200
}
Path Parameters
- user (required): The name of the user.
- dbname (required): The name of the database.
Return Codes
- 201: Returned if the user can be added by the server
- 400: If the JSON representation is malformed or mandatory data is missing from the request.
Examples
shell> curl -X PUT --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; charset=utf-8
{
"_system" : "rw",
"error" : false,
"code" : 200
}
shell> curl -X PUT --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; charset=utf-8
List the databases available to a User
List available database to the specified user
GET /_api/user/{user}/database/
Path Parameters
- user (required): The name of the user for which you want to query the databases.
Fetch the list of databases available to the specified user. You need permission to the _system database in order to execute this REST call.
Example:
shell> curl --dump - http://localhost:8529/_api/user/anotherAdmin@secapp/database/
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"result" : {
},
"error" : false,
"code" : 200
}
Return Codes
- 200: Returned if the list of available databases can be returned.
- 400: If the access privileges aren't right etc.
Examples
shell> curl --dump - http://localhost:8529/_api/user/anotherAdmin@secapp/database/
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"result" : {
},
"error" : false,
"code" : 200
}
shell> curl --dump - http://localhost:8529/_api/user/anotherAdmin@secapp/database/
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
Replace User
replace an existing user with a new one.
PUT /_api/user/{user}
Path Parameters
- user (required): The name of the user
A json post document with these Properties is required:
- passwd: The user password as a string. Specifying a password is mandatory, but the empty string is allowed for passwords
- active: An optional flag that specifies whether the user is active. If not specified, this will default to true
- extra: An optional JSON object with arbitrary extra data about the user.
Replaces the data of an existing user. The name of an existing user must be specified in user. You can only change the password of your self. You need access to the _system database to change the active flag.
Example:
shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/user/admin@myapp <<EOF
{
"passwd" : "secure"
}
EOF
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"user" : "admin@myapp",
"active" : true,
"extra" : {
},
"changePassword" : false,
"error" : false,
"code" : 200
}
Return Codes
- 200: Is returned if the user data can be replaced by the server
- 400: The JSON representation is malformed or mandatory data is missing from the request
- 404: The specified user does not exist
Examples
shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/user/admin@myapp <<EOF
{
"passwd" : "secure"
}
EOF
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"user" : "admin@myapp",
"active" : true,
"extra" : {
},
"changePassword" : false,
"error" : false,
"code" : 200
}
shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/user/admin@myapp <<EOF
{
"passwd" : "secure"
}
EOF
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
Update User
modify attributes of an existing user
PATCH /_api/user/{user}
Path Parameters
- user (required): The name of the user
A json post document with these Properties is required:
- passwd: The user password as a string. Specifying a password is mandatory, but the empty string is allowed for passwords
- active: An optional flag that specifies whether the user is active. If not specified, this will default to true
- extra: An optional JSON object with arbitrary extra data about the user.
Partially updates the data of an existing user. The name of an existing user must be specified in user. You can only change the password of your self. You need access to the _system database to change the active flag.
Example:
shell> curl -X PATCH --data-binary @- --dump - http://localhost:8529/_api/user/admin@myapp <<EOF
{
"passwd" : "secure"
}
EOF
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"user" : "admin@myapp",
"active" : true,
"extra" : {
},
"changePassword" : false,
"error" : false,
"code" : 200
}
Return Codes
- 200: Is returned if the user data can be replaced by the server
- 400: The JSON representation is malformed or mandatory data is missing from the request
- 404: The specified user does not exist
Examples
shell> curl -X PATCH --data-binary @- --dump - http://localhost:8529/_api/user/admin@myapp <<EOF
{
"passwd" : "secure"
}
EOF
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"user" : "admin@myapp",
"active" : true,
"extra" : {
},
"changePassword" : false,
"error" : false,
"code" : 200
}
shell> curl -X PATCH --data-binary @- --dump - http://localhost:8529/_api/user/admin@myapp <<EOF
{
"passwd" : "secure"
}
EOF
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
Remove User
delete a user permanently.
DELETE /_api/user/{user}
Path Parameters
- user (required): The name of the user
Removes an existing user, identified by user. You need access to the _system database.
Example:
shell> curl -X DELETE --data-binary @- --dump - http://localhost:8529/_api/user/userToDelete@myapp <<EOF
{
}
EOF
HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
{
"error" : false,
"code" : 202
}
Return Codes
- 202: Is returned if the user was removed by the server
- 404: The specified user does not exist
Examples
shell> curl -X DELETE --data-binary @- --dump - http://localhost:8529/_api/user/userToDelete@myapp <<EOF
{
}
EOF
HTTP/1.1 202 Accepted
content-type: application/json; charset=utf-8
{
"error" : false,
"code" : 202
}
Fetch User
fetch the properties of a user.
GET /_api/user/{user}
Path Parameters
- user (required): The name of the user
Fetches data about the specified user. You can fetch information about yourself or you need permission to the _system database in order to execute this REST call.
Example:
shell> curl --dump - http://localhost:8529/_api/user/admin@myapp
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"user" : "admin@myapp",
"active" : true,
"extra" : {
},
"changePassword" : false,
"error" : false,
"code" : 200
}
Return Codes
- 200: The user was found.
- 404: The user with the specified name does not exist.
Examples
shell> curl --dump - http://localhost:8529/_api/user/admin@myapp
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"user" : "admin@myapp",
"active" : true,
"extra" : {
},
"changePassword" : false,
"error" : false,
"code" : 200
}
shell> curl --dump - http://localhost:8529/_api/user/admin@myapp
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
List available Users
fetch the properties of a user.
GET /_api/user/
Fetches data about all users. You can only execute this call if you have access to the _system database. 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: An optional JSON object with arbitrary extra data about the user.
- changePassword: An optional flag that specifies whether the user must change the password or not.
Example:
shell> curl --dump - http://localhost:8529/_api/user
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"result" : [
{
"user" : "root",
"active" : true,
"extra" : {
},
"changePassword" : false
},
{
"user" : "admin",
"active" : true,
"extra" : {
},
"changePassword" : false
},
{
"user" : "tester",
"active" : false,
"extra" : {
},
"changePassword" : false
},
{
"user" : "admin@example",
"active" : true,
"extra" : {
},
"changePassword" : false
}
],
"error" : false,
"code" : 200
}
Return Codes
- 200: The users that were found.
Examples
shell> curl --dump - http://localhost:8529/_api/user
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
{
"result" : [
{
"user" : "root",
"active" : true,
"extra" : {
},
"changePassword" : false
},
{
"user" : "admin",
"active" : true,
"extra" : {
},
"changePassword" : false
},
{
"user" : "tester",
"active" : false,
"extra" : {
},
"changePassword" : false
},
{
"user" : "admin@example",
"active" : true,
"extra" : {
},
"changePassword" : false
}
],
"error" : false,
"code" : 200
}
shell> curl --dump - http://localhost:8529/_api/user
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8