HTTP interface for authentication

Client authentication can be achieved by using the Authorization HTTP header in client requests. ArangoDB supports authentication via HTTP Basic or JWT.

Authentication is turned on by default for all internal database APIs but turned off for custom Foxx apps. To toggle authentication for incoming requests to the internal database APIs, use the --server.authentication startup option. This option is turned on by default so authentication is required for the database APIs.

There is an additional option to control authentication for custom Foxx apps. The --server.authentication-system-only startup option controls whether authentication is required only for requests to the internal database APIs and the admin interface. It is turned on by default, meaning that other APIs (this includes custom Foxx apps) do not require authentication.

The default values allow exposing a public custom Foxx API built with ArangoDB to the outside world without the need for HTTP authentication, but still protecting the usage of the internal database APIs (i.e. /_api/, /_admin/) with HTTP authentication.

If the server is started with the --server.authentication-system-only option set to false, all incoming requests need HTTP authentication if the server is configured to require HTTP authentication (i.e. --server.authentication true). Setting the option to true makes the server require authentication only for requests to the internal database APIs and allows unauthenticated requests to all other URLs.

Here is a short summary:

• --server.authentication true --server.authentication-system-only true: This requires authentication for all requests to the internal database APIs but not custom Foxx apps. This is the default setting.
• --server.authentication true --server.authentication-system-only false: This requires authentication for all requests (including custom Foxx apps).
• --server.authentication false: Authentication is disabled for all requests.

Whenever authentication is required and the client has not yet authenticated, ArangoDB returns HTTP 401 (Unauthorized). It also sends the Www-Authenticate response header, indicating that the client should prompt the user for username and password if supported. If the client is a browser, then sending back this header normally triggers the display of the browser-side HTTP authentication dialog. As showing the browser HTTP authentication dialog is undesired in AJAX requests, ArangoDB can be told to not send the Www-Authenticate header back to the client. Whenever a client sends the X-Omit-Www-Authenticate HTTP header (with an arbitrary value) to the server, ArangoDB only sends status code 401, but no Www-Authenticate header. This allows clients to implement credentials handling and bypassing the browser’s built-in dialog.

HTTP Basic Authentication

ArangoDB supports basic authentication with a user name and password. The name and the password of an ArangoDB user account need to be separated by a colon and the entire string needs to be Base64-encoded. The resulting value can be used in the Authorization header of an HTTP request, indicating that the authorization scheme is Basic.

For example, if the name is user and the password pass, the temporary string that needs to be encoded is user:pass. The Base64-encoded value is dXNlcjpwYXNz (e.g. using the btoa() JavaScript function in a browser). The HTTP request header to authenticate is a follows:

Authorization: Basic dXNlcjpwYXNz

If you use a tool like cURL, you can manually specify this header as follows:

curl -H 'Authorization: Basic dXNlcjpwYXNz' ...

However, cURL can also take care of the authentication and specifically the encoding of the credentials for you:

curl -u user:pass ...

You can also authenticate with Access tokens. Use the access token as the password. You can omit the user name in this case:

curl -u:the_access_token

If you specify the user name, it must match the name encoded in the token.

Bearer Token Authentication

ArangoDB uses a standard JWT-based authentication method. To authenticate via JWT, you must first obtain a JWT token with a signature generated via HMAC with SHA-256. The secret may either be set using --server.jwt-secret or it is randomly generated on server startup.

For more information on JWT please consult RFC7519 and jwt.io .

JWT user tokens

To authenticate with a specific user account, you need to supply a JWT token containing the preferred_username field with the username. You can either let ArangoDB generate this token for you via an API call or you can generate it yourself (only if you know the JWT secret).

ArangoDB offers a RESTful API to generate user tokens for you if you know the username and password. To do so, send a POST request to this endpoint:

/_open/auth

The request body needs to contain the username and password JSON-encoded like so:

{
  "username": "root",
  "password": "rootPassword"
}

You can also use Access tokens for creating JWTs. Provide the access token as the password. You can omit the username:

{
  "password": "theAccessToken"
}

If you specify the user name, it must match the name encoded in the token.

On success, the endpoint returns a **200 OK** and an answer containing
the JWT in a JSON-encoded object like so:

```json
{ "jwt": "eyJhbGciOiJIUzI1NiI..x6EfI" }

This JWT should then be used within the Authorization HTTP header in subsequent requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiI..x6EfI

You can find the expiration date of the JWT token in the exp field, encoded as Unix timestamp in seconds. Please note that all JWT tokens must contain the iss field with string value arangodb. As an example the decoded JWT body would look like this:

{
  "exp": 1540381557,
  "iat": 1537789.55727901,
  "iss": "arangodb",
  "preferred_username": "root"
}

Create a JWT session token

JWT superuser tokens

To access specific internal APIs as well as Agency and DB-Server instances a token generated via POST /_open/auth is not good enough. For these special APIs, you need to generate a special JWT token which grants superuser access. Note that using superuser access for normal database operations is not advised.

For your convenience it is possible to generate this token via the ArangoDB starter CLI.

Should you wish to generate the JWT token yourself with a tool of your choice, you need to include the correct body. The body must contain the iss field with string value arangodb and the server_id field with an arbitrary string identifier:

{
  "exp": 1537900279,
  "iat": 1537800279,
  "iss": "arangodb",
  "server_id": "myclient"
}

For example to generate a token via the jwtgen tool  (note the lifetime of one hour):

jwtgen -s <my-secret> -e 3600 -v -a "HS256" -c 'iss=arangodb' -c 'server_id=myclient'
curl -v -H "Authorization: bearer $(jwtgen -s <my-secret> -e 3600 -a "HS256" -c 'iss=arangodb' -c 'server_id=myclient')" http://<database-ip>:8529/_api/version

Access tokens

Access tokens act like passwords in authentication. Unlike normal credentials comprised of a username and a password, you can create multiple access tokens for a single user account. This is akin to having multiple passwords. You can set a desired expiration date for each access token (typically a few weeks or months) and individually revoke tokens on the server-side if necessary. You can use every access tokens for a different purpose, like different services that access ArangoDB using the same account, for fine-grained access control without having to change the password if you want to revoke access for one of the services.

You can use access tokens instead of the password to generate JWT session tokens (recommended) or use them directly as password in HTTP Basic Authentication (for backwards compatibility).

You need to create any user accounts first that you want to add access tokens to, see Create a user.

Create an access token

Create an access token for the root user:

curl -X POST --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/token/root' <<'EOF'
{
  "name": "Token for Service A",
  "valid_until": 1782864000
}
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: 280
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

{ 
  "id" : 1, 
  "name" : "Token for Service A", 
  "valid_until" : 1782864000, 
  "created_at" : 1755773629, 
  "fingerprint" : "v1...78227d", 
  "active" : true, 
  "token" : "v1.7b2265223a313738323836343030302c2263223a313735353737333632392c2275223a22726f6f74222c2272223a2234626d6668785a49633047683068643749575878227d" 
}

List all access tokens

List the access tokens of the root user:

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

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

{ 
  "tokens" : [ 
    { 
      "id" : 1, 
      "name" : "Token for Service A", 
      "valid_until" : 1782864000, 
      "created_at" : 1755773629, 
      "fingerprint" : "v1...78227d", 
      "active" : true 
    } 
  ] 
}

Delete an access token

Delete an access tokens of the root user:

curl -X DELETE --header 'accept: application/json' --dump - 'http://localhost:8529/_api/token/root/1'

HTTP/1.1 200 OK
content-type: text/plain
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: 0
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

Hot-reload JWT secrets

To reload the JWT secrets of a local arangod process without a restart, you may use the following RESTful API. A POST request reloads the secret, a GET request may be used to load information about the currently used secrets.

Get information about the loaded JWT secrets

Hot-reload the JWT secret(s) from disk

Example result:

{
  "error": false,
  "code": 200,
  "result": {
    "active": {
      "sha256": "c6c1021286dfe870b7050f9e704df93c7f1de3c89dbdadc3fb30394bebd81e97"
    },
    "passive": [
      {
        "sha256": "6d2fe32dc4249ef7e7359c6d874fffbbf335e832e49a2681236e1b686af78794"
      },
      {
        "sha256": "448a28491967ea4f7599f454af261a685153c27a7d5748456022565947820fb9"
      },
      {
        "sha256": "6745d49264bdfc2e89d4333fe88f0fce94615fdbdb8990e95b5fda0583336da8"
      }
    ]
  }
}