Authorize requests

Unless authentication is disabled on the server, all requests must be authorized using the login credentials of a valid user.

Request are authorized through an Authorization header. Both basic and bearer authentication are supported.

If authentication is disabled on the server, requests can be sent without an Authorization header.

Basic authentication

The header format for basic authentication follows the standard format (RFC 7617):

Authorization: Basic <base64(username:password)>

Example 1. Basic authentication

To authenticate as user neo4j with password verysecret, first join them with a colon:

neo4j:verysecret

and then base64-encode that value:

bmVvNGo6dmVyeXNlY3JldA==

How to base64-encode a string

To base64-encode a string on a Linux or Mac machine, use the built-in base64 command:

echo -n "neo4j:verysecret" | base64

To obtain the final header, prepend Basic to the base64-encoding of the credentials:

Authorization: Basic bmVvNGo6dmVyeXNlY3JldA==

Bearer authentication

The header format to authenticate with a bearer token is:

Authorization: Bearer <base64(token)>

Example 2. Bearer authentication

To authenticate with the token xbhkjnlvianztghqwawxqfe, first base64-encode it:

eGJoa2pubHZpYW56dGdocXdhd3hxZmUK

How to base64-encode a string

To base64-encode a string on a Linux or Mac machine, use the built-in base64 command:

echo -n "xbhkjnlvianztghqwawxqfe" | base64

To obtain the final header, prepend Bearer to the base64-encoding of the credential:

Authorization: Bearer eGJoa2pubHZpYW56dGdocXdhd3hxZmUK

It is up to your application to generate bearer tokens via your SSO provider. The Neo4j server should also be set up to work with SSO. For more information, see Configuring Neo4j Single Sign-On (SSO).

Errors

Missing authorization

If an Authorization header is not supplied (and authentication is not disabled), the server replies with status 401 Forbidden and an error.

Example request

POST http://localhost:7474/db/neo4j/tx/commit
Accept: application/json;charset=UTF-8
Content-Type: application/json

Example response

401: Unauthorized
Content-Type: application/json;charset=utf-8

{
  "errors" : [ {
    "code" : "Neo.ClientError.Security.Unauthorized",
    "message" : "No authentication header supplied."
  } ]
}

Incorrect authentication

If an incorrect username or password is provided, or if they fail to be properly base64-encoded, the server replies with status 401 Forbidden and an error.

Example request

POST http://localhost:7474/db/neo4j/tx/commit
Accept: application/json;charset=UTF-8
Authorization: Basic bmVvNGo6aW5jb3JyZWN0
Content-Type: application/json

Example response

401: Unauthorized
Content-Type: application/json;charset=utf-8

{
  "errors" : [ {
    "code" : "Neo.ClientError.Security.Unauthorized",
    "message" : "Invalid username or password."
  } ]
}

Invalid authentication

If the content of the Authorization header fails to be properly base64-encoded, the server replies with status 401 Forbidden and an error.

Example request

POST http://localhost:7474/db/neo4j/tx/commit
Accept: application/json;charset=UTF-8
Authorization: Basic not-proper-base64
Content-Type: application/json

Example response

401: Unauthorized
Content-Type: application/json;charset=utf-8

{
  "errors" : [ {
    "code": "Neo.ClientError.Request.InvalidFormat",
    "message": "Invalid authentication header."
  } ]
}