add api to content nav

modules/ROOT/content-nav.adoc

@@ -102,6 +102,11 @@ Generic Start
 
 * Connecting applications
 ** xref:connecting-applications/overview.adoc[Drivers and libraries]
+
+* Aura API
+** xref:platform/api/overview.adoc[]
+** xref:platform/api/authentication.adoc[]
+** link:{neo4j-docs-base-uri}/aura/platform/api/specification/[API Specification]
 ////
 AuraDB End
 ////

modules/ROOT/pages/platform/api/authentication.adoc

@@ -6,13 +6,14 @@ The Aura API uses OAuth 2.0 for API authentication.
 
 == Creating credentials
 
-[NOTE]
-====
-Enterprise users have unrestricted access to creating API 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.
-====
+API credentials are linked to the user account, inheriting its capabilities and roles.
+The API credentials never expire unless you delete them.
 
-. Navigate to the https://console.neo4j.io/#account[Neo4j Aura console Account Details page] in your browser.
+To create credentials:
+
+. Navigate to the https://console.neo4j.io/#account[Neo4j Aura Console Account Details page] in your browser.
 . Select the *Create* button in the *Aura API Credentials* section.
 . Enter a *Client name*, and select *Create*.
 . Securely save the *Client ID* and *Client Secret* you are given in the resulting modal; you will need these for the next step.
@@ -63,7 +64,7 @@ Authentication to the token endpoint uses HTTP Basic Authentication, where the c
 |===
 |Parameter |Value
 
-|grant_type
+|`grant_type`
 |`client_credentials`
 |===
 
@@ -112,7 +113,7 @@ response = requests.request(
 print(response.json())
 ----
 
-<1> `client_id` and `client_secret` must be set to the values obtained from the Aura console.
+<1> `client_id` and `client_secret` must be set to the values obtained from the Aura Console.
 =====
 ====
 
@@ -123,12 +124,14 @@ print(response.json())
 ----
 {
   "access_token": "<token>", <1>
-  "expires_in": 3600,
+  "expires_in": 3600, <2>
   "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.
+<2> The value of `expires_in` is the token expiration time in seconds. 
+Once the token expires, the application must request a new one.
 
 ==== HTTP response codes
 
@@ -157,7 +160,17 @@ print(response.json())
 |The request body is missing.
 |===
 
+=== Excessive token requests
+
+Excessive token requests may cause inefficiencies or rate-limiting. 
+You can optimize your API usage by following these steps:
+
+* *Retrieve the token once per hour:* As tokens remain valid for an hour, reduce the frequency of token requests and reuse the same token for multiple API calls.
+
+* *Implement token caching:* Store the token securely within your system to reuse it for subsequent requests during its validity period, minimizing unnecessary calls to the endpoint.
+
 === Token expiration
 
-If you attempt to send a request to the Aura API, authenticated using an expired access token, you will receive a 403 Forbidden response.
-You will need to obtain a new token to continue using the API.
+Access tokens are temporary and expire after one hour.
+If you send a request to the Aura API using an expired token, you will receive a `403 Forbidden` response. 
+To continue using the API, you must obtain a new token using the Aura API credentials.

modules/ROOT/pages/platform/api/overview.adoc

@@ -2,7 +2,10 @@
 = Overview
 :description: This page introduces the Aura API.
 
-The Aura API allows you to programmatically perform actions on your Aura instances without the need to log in to the console.
+label:AuraDB-Virtual-Dedicated-Cloud[]
+label:AuraDS-Enterprise[]
+
+The Aura API allows you to programmatically perform actions on your Aura instances without the need to log in to the Console.
 
 A complete list of the available endpoints can be seen and tested in the link:{neo4j-docs-base-uri}/aura/platform/api/specification/[API Specification].
 
@@ -34,13 +37,15 @@ The following example shows how to use the base URL and versioning to make a req
 
 == Retries
 
-In the event of `5xx` server error responses, you may consider retrying the request after a delay if it is safe to do so. The response may include a `Retry-After` header with a suggestion of a suitable minimum delay before attempting to retry.
+In the event of `5xx` server error responses, you may consider retrying the request after a delay if it is safe to do so.
+The response may include a `Retry-After` header with a suggestion of a suitable minimum delay before attempting to retry.
 
-Rate limiting is set to 125 requests per minute.
+The global rate limit for all requests is 125 requests per minute.
 
-You should consider your use of the Rate Limit before attempting to retry, and we recommend using an exponential backoff delay with a limited number of retries before giving up.
+You should consider your use of the rate limit before attempting to retry, and it is recommended that you use an exponential backoff delay with a limited number of retries before giving up.
 
-A request is only guaranteed to be safe to retry if it uses an idempotent HTTP method, such as `GET`. If for example, you attempt to retry a request for creating an instance, you may end up with duplicate instances and end up being charged extra as a result.
+A request is only guaranteed to be safe to retry if it uses an idempotent HTTP method, such as `GET`.
+If, for example, you retry a request for creating an instance, you may end up with duplicate instances and end up being charged extra as a result.
 
 In the case of `429 Too Many Requests`, we would recommend slowing down the rate of all requests sent from your client application and consider retrying with a suitable minimum delay and backoff strategy.
 
@@ -52,4 +57,4 @@ An `X-Request-Id` response header is returned with each request and can be used
 
 The value of this header contains a unique ID that can be used to track the journey of a request.
 
-If you run into any issues with a particular request, you can https://support.neo4j.com/[raise a support ticket] and provide the `X-Request-Id`.
+If you run into any issues with a particular request, you can https://support.neo4j.com/[raise a support ticket] and provide the `X-Request-Id`.