Authentication

The Aura API uses OAuth 2.0 for API authentication.

Creating credentials

AuraDB Virtual Dedicated Cloud users, and AuraDS Enterprise users have unrestricted access to creating API credentials. However, users with Free and Professional instances must have entered billing information or be a member of a marketplace project before they can create API credentials.

  1. Navigate to the Neo4j Aura Console Account Details page in your browser.

  2. Select the Create button in the Aura API Credentials section.

  3. Enter a Client name, and select Create.

  4. Securely save the Client ID and Client Secret you are given in the resulting modal; you will need these for the next step.

You cannot retrieve your secret after you close the modal, so save it securely.

Authenticating API requests

To authenticate API requests to the Aura API, you must provide a Bearer Token in the Authorization header of each request as shown below:

Authorization: Bearer <access_token>

You can use the Authorize button on the Aura API page to authenticate and test endpoints directly using your client ID and client secret. The UI sets the Authorization header for you.

Token endpoint

You can use the following /oauth/token endpoint to obtain a Bearer Token for authenticating API requests.

Authentication to the token endpoint uses HTTP Basic Authentication, where the client ID and client secret are provided as the username and password, respectively.

Request parameters

  • Method: POST

  • Token URL: https://api.neo4j.io/oauth/token

Request header

Parameter Value

Authorization [1]

Basic <credentials> [2]

Content-Type

application/x-www-form-urlencoded

1. This header is set for you when providing your client ID as the username and client secret as the password.

2. Where <credentials> is the base64-encoded string of your client ID and client secret, joined by a colon (:).

Request body

Parameter Value

grant_type

client_credentials

Both the request and response contain sensitive information and must be kept secure.

You are responsible for keeping the client credentials and access tokens confidential, whether in transit (by specifying HTTPS), if stored at rest, in log files, etc.

Request examples

curl --request POST 'https://api.neo4j.io/oauth/token' \
     --user '<client_id>:<client_secret>' \ (1)
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data-urlencode 'grant_type=client_credentials'
1 The --user option sets the Authorization header for you, handling the base64 encoding of the client ID and client secret. 
import requests
from requests.auth import HTTPBasicAuth

# Make the request to the Aura API Auth endpoint
response = requests.request(
    "POST",
    "https://api.neo4j.io/oauth/token",
    headers={"Content-Type": "application/x-www-form-urlencoded"},
    data={"grant_type": "client_credentials"},
    auth=HTTPBasicAuth(client_id, client_secret) (1)
)

print(response.json())
1 client_id and client_secret must be set to the values obtained from the Aura Console.

Response body example

{
  "access_token": "<token>", (1)
  "expires_in": 3600,
  "token_type": "bearer"
}
1 The access_token returned here is what you will provide as the Bearer Token in the Authorization header of Aura API requests.

HTTP response codes

Code Message Description

200

Success

Access token requested successfully.

400

Bad Request

Request is invalid.

401

Unauthorized

The provided credentials are invalid, expired, or revoked.

403

Forbidden

The request body is invalid.

404

Not Found

The request body is missing.

Token expiration

If you send a request to the Aura API while authenticated with an expired access token, you will receive a 403 Forbidden response. You will need to obtain a new token to continue using the API.