diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index c61978cb..751870ed 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -57,12 +57,11 @@ * *Products* * xref:aura-graphql/index.adoc[] -** xref:aura-graphql/prerequisites.adoc[] -** xref:aura-graphql/deploy-and-operate.adoc[] -** xref:aura-graphql/authentication-providers.adoc[] -** xref:aura-graphql/using-your-api.adoc[] -** xref:aura-graphql/end-of-beta-phase.adoc[] - +** xref:aura-graphql/api-creation.adoc[] +** xref:aura-graphql/api-update.adoc[] +** xref:aura-graphql/api-deletion.adoc[] +** xref:aura-graphql/api-usage.adoc[] +** xref:aura-graphql/aura-cli-configuration.adoc[] * xref:introspector.adoc[Introspector] diff --git a/modules/ROOT/images/aura-graphql/aura-cli/account-dropdown.png b/modules/ROOT/images/aura-graphql/aura-cli/account-dropdown.png new file mode 100644 index 00000000..dd459276 Binary files /dev/null and b/modules/ROOT/images/aura-graphql/aura-cli/account-dropdown.png differ diff --git a/modules/ROOT/images/aura-graphql/aura-cli/api-keys-create.png b/modules/ROOT/images/aura-graphql/aura-cli/api-keys-create.png new file mode 100644 index 00000000..e1218f80 Binary files /dev/null and b/modules/ROOT/images/aura-graphql/aura-cli/api-keys-create.png differ diff --git a/modules/ROOT/images/aura-graphql/aura-cli/api-keys-created.png b/modules/ROOT/images/aura-graphql/aura-cli/api-keys-created.png new file mode 100644 index 00000000..edc1bbca Binary files /dev/null and b/modules/ROOT/images/aura-graphql/aura-cli/api-keys-created.png differ diff --git a/modules/ROOT/images/aura-graphql/aura-cli/api-keys.png b/modules/ROOT/images/aura-graphql/aura-cli/api-keys.png new file mode 100644 index 00000000..2f03714a Binary files /dev/null and b/modules/ROOT/images/aura-graphql/aura-cli/api-keys.png differ diff --git a/modules/ROOT/images/aura-graphql/console-classic-api-keys.png b/modules/ROOT/images/aura-graphql/console-classic-api-keys.png deleted file mode 100644 index e7b7ecff..00000000 Binary files a/modules/ROOT/images/aura-graphql/console-classic-api-keys.png and /dev/null differ diff --git a/modules/ROOT/images/aura-graphql/console-classic-home.png b/modules/ROOT/images/aura-graphql/console-classic-home.png deleted file mode 100644 index e43c629b..00000000 Binary files a/modules/ROOT/images/aura-graphql/console-classic-home.png and /dev/null differ diff --git a/modules/ROOT/images/aura-graphql/console_data_api_confirm_delete_menu.png b/modules/ROOT/images/aura-graphql/console_data_api_confirm_delete_menu.png deleted file mode 100644 index ab188242..00000000 Binary files a/modules/ROOT/images/aura-graphql/console_data_api_confirm_delete_menu.png and /dev/null differ diff --git a/modules/ROOT/images/aura-graphql/console_data_api_delete_menu.png b/modules/ROOT/images/aura-graphql/console_data_api_delete_menu.png deleted file mode 100644 index edb30b03..00000000 Binary files a/modules/ROOT/images/aura-graphql/console_data_api_delete_menu.png and /dev/null differ diff --git a/modules/ROOT/images/aura-graphql/console_data_api_edit.png b/modules/ROOT/images/aura-graphql/console_data_api_edit.png deleted file mode 100644 index 81dbeaf1..00000000 Binary files a/modules/ROOT/images/aura-graphql/console_data_api_edit.png and /dev/null differ diff --git a/modules/ROOT/images/aura-graphql/console_data_api_edit_menu.png b/modules/ROOT/images/aura-graphql/console_data_api_edit_menu.png deleted file mode 100644 index 4aa4a48b..00000000 Binary files a/modules/ROOT/images/aura-graphql/console_data_api_edit_menu.png and /dev/null differ diff --git a/modules/ROOT/images/aura-graphql/console_data_api_sidebar.png b/modules/ROOT/images/aura-graphql/console_data_api_sidebar.png deleted file mode 100644 index 2f061cf3..00000000 Binary files a/modules/ROOT/images/aura-graphql/console_data_api_sidebar.png and /dev/null differ diff --git a/modules/ROOT/images/aura-graphql/create/auth-providers.png b/modules/ROOT/images/aura-graphql/create/auth-providers.png new file mode 100644 index 00000000..4c7d52b3 Binary files /dev/null and b/modules/ROOT/images/aura-graphql/create/auth-providers.png differ diff --git a/modules/ROOT/images/aura-graphql/create/cors-policy.png b/modules/ROOT/images/aura-graphql/create/cors-policy.png new file mode 100644 index 00000000..9f19fe80 Binary files /dev/null and b/modules/ROOT/images/aura-graphql/create/cors-policy.png differ diff --git a/modules/ROOT/images/aura-graphql/create/details.png b/modules/ROOT/images/aura-graphql/create/details.png new file mode 100644 index 00000000..50db3d8f Binary files /dev/null and b/modules/ROOT/images/aura-graphql/create/details.png differ diff --git a/modules/ROOT/images/aura-graphql/create/save-api-key.png b/modules/ROOT/images/aura-graphql/create/save-api-key.png new file mode 100644 index 00000000..a53af919 Binary files /dev/null and b/modules/ROOT/images/aura-graphql/create/save-api-key.png differ diff --git a/modules/ROOT/images/aura-graphql/create/sizing.png b/modules/ROOT/images/aura-graphql/create/sizing.png new file mode 100644 index 00000000..a770aa33 Binary files /dev/null and b/modules/ROOT/images/aura-graphql/create/sizing.png differ diff --git a/modules/ROOT/images/aura-graphql/create/type-definitions.png b/modules/ROOT/images/aura-graphql/create/type-definitions.png new file mode 100644 index 00000000..79c9d2c1 Binary files /dev/null and b/modules/ROOT/images/aura-graphql/create/type-definitions.png differ diff --git a/modules/ROOT/images/aura-graphql/delete/confirm-deletion.png b/modules/ROOT/images/aura-graphql/delete/confirm-deletion.png new file mode 100644 index 00000000..689f4463 Binary files /dev/null and b/modules/ROOT/images/aura-graphql/delete/confirm-deletion.png differ diff --git a/modules/ROOT/images/aura-graphql/unified-console-account-dropdown.png b/modules/ROOT/images/aura-graphql/unified-console-account-dropdown.png deleted file mode 100644 index b57800a0..00000000 Binary files a/modules/ROOT/images/aura-graphql/unified-console-account-dropdown.png and /dev/null differ diff --git a/modules/ROOT/images/aura-graphql/unified-console-api-keys.png b/modules/ROOT/images/aura-graphql/unified-console-api-keys.png deleted file mode 100644 index 78dd6459..00000000 Binary files a/modules/ROOT/images/aura-graphql/unified-console-api-keys.png and /dev/null differ diff --git a/modules/ROOT/images/aura-graphql/unified-console-create-api-key.png b/modules/ROOT/images/aura-graphql/unified-console-create-api-key.png deleted file mode 100644 index be651acc..00000000 Binary files a/modules/ROOT/images/aura-graphql/unified-console-create-api-key.png and /dev/null differ diff --git a/modules/ROOT/images/aura-graphql/unified-console-home.png b/modules/ROOT/images/aura-graphql/unified-console-home.png deleted file mode 100644 index 53b11d04..00000000 Binary files a/modules/ROOT/images/aura-graphql/unified-console-home.png and /dev/null differ diff --git a/modules/ROOT/pages/aura-graphql/api-creation.adoc b/modules/ROOT/pages/aura-graphql/api-creation.adoc new file mode 100644 index 00000000..f34615c9 --- /dev/null +++ b/modules/ROOT/pages/aura-graphql/api-creation.adoc @@ -0,0 +1,161 @@ += Creating a GraphQL API + + +== Before you start + +Make sure that you have: + +* The ID, username and password for the AuraDB. +* Your type definitions. +* If you intend to use JWKS for authentication, the URL from your identity provider that will be used to verify JWKS tokens. + +If you intend to use the Aura CLI, follow the guidance provided in xref:aura-graphql/aura-cli-configuration.adoc[] before proceeding. + + +== Console + +. In the Aura Console, select **Data APIs** from the left side navigation. +. Use **Create API** and fill in the details in the **Create GraphQL Data API** dialog. ++ +image::aura-graphql/create/details.png[] ++ +[CAUTION] +==== +If you set **Enable introspection** and **Enable field suggestions** for production systems the information they provide can be used by malicious actors to reverse-engineer your GraphQL schema and execute arbitrary operations. + +**Enable introspection** allows you to query the schema and discover the available queries, mutations, subscriptions, types and fields in the GraphQL API. + +**Enable field suggestions** provides suggestions that hint towards GraphQL typos. +Even with just field suggestions enabled, it is possible for a malicious actor to discover your entire schema. +==== ++ +. Type definitions ++ +This is where you describe the graph database in the AuraDB that the GraphQL API will be used with. +The type definitions are the same as those used with Neo4j GraphQL Library with the exception that custom resolvers cannot be used. ++ +If you already have data in the AuraDB, a quick way to obtain type definitions is to use the https://graphql-toolbox.neo4j.io[Neo4j GraphQL Toolbox]. This facility has the ability to connect to an AuraDB, automatically create type definitions and allow GraphQL operations. ++ +Alternatively you can write your own type definitions from first principles by following the guidance provided in xref:index.adoc[Neo4j GraphQL Library] documentation. ++ +If you are using GraphQL Federation then make sure to select **Enable GraphQL subgraph**. ++ +image::aura-graphql/create/type-definitions.png[] ++ +. Cross-Origin Resource Sharing (CORS) policy ++ +If a browser based application will be using this GraphQL API, add an entry in your Cross-Origin Resource Sharing (CORS) policy. +CORS is a browser-based security mechanism that prevents web pages from accessing resources from a server with a different origin. +Allow the URL that serves the browser application by adding it to the CORS policy. +This includes development environments such as node.js, which serves content on your localhost or similar. +This also holds for using web-based tooling for GraphQL APIs such as https://studio.apollographql.com/[Apollo Studio]. ++ +This is not needed if a non-browser-based application is using the GraphQL API as CORS does not apply to those. +For example, if you are trying out GraphQL operations using cURL. ++ +[NOTE] +==== +The URL entered in the CORS policy must be an exact match. +For example, http://localhost is not the same as http://localhost:3000/. +Wildcards are not supported. +==== ++ +To add a CORS policy entry, enter the exact URL, including HTTP/S and any port number, in the **Origin box**. +If you need multiple entries, select **Add allowed origin**. ++ +image::aura-graphql/create/cors-policy.png[] ++ +. Authentication providers ++ +All requests to the GraphQL API are authenticated and there are two options for the type of authentication: API key or JSON Web Key Set (JWKS). +It is possible to use these in combination and have multiples of each. ++ +After choosing the authentication provider from the dropdown list, enter a friendly name. +This is all that is needed when using API key. +The API key will be shown after the GraphQL API key has been created. +If you are using JWKS, provide a friendly name and the URL from your identity provider that is used to verify JWKS tokens. ++ +Add more more providers via **Add authentication provider**. ++ +An authentication provider can be removed by selecting the trash icon. ++ +image::aura-graphql/create/auth-providers.png[] ++ +[CAUTION] +==== +It is not recommended to use API keys with user-facing applications that are using the GraphQL API. +This is due to the risk of the API key being visible to malicious users and very little control over GraphQL operations. +A 3rd party identity provider with JWKS provides better security and allows for granular security rules, based on information within the JWKS token, to be defined within the type definitions to control GraphQL operations. +==== ++ +. Sizing ++ +Sizing a GraphQL API is based on the size and complexity of the type definitions and the workload that is serviced. +Larger sizes have a higher hourly cost. +If the cost is not displayed, refer to the agreement you have with Neo4j. ++ +image::aura-graphql/create/sizing.png[] ++ +. Creation ++ +At this point the configuration is complete for the GraphQL API. +Select **Create** to proceed and create the GraphQL API. +Alternatively, **Cancel** the process at top right of the page. ++ +. API key ++ +If you chose to use an API key with the GraphQL API it is now displayed. +Store this information securely as it cannot be retrieved again. +Select **I understand** and then **Close** once you have done this. ++ +image::aura-graphql/create/save-api-key.png[] ++ +. The GraphQL API will now be provisioned. +You can see the status via **Data APIs** from the left side navigation. +When the status changes to "Ready", the API is ready to use. +If it has a status of 'Error', use the three dots icon and **Edit** from the menu to change the configuration. + + +== Aura CLI + +Like the Console, the Aura CLI can also be used to create a GraphQL API. +There is a difference: on creation, only an API Key authentication provider is created. +The authentication providers can be modified using subsequent CLI commands. + +To create a GraphQL API with the Aura CLI, proceed as follows. + +. Find the AuraDB instance ID ++ +From the table, locate the ID of the Aura instance that the GraphQL API will be used with. ++ +[source, bash, indent=0] +---- +aura-cli instance list +---- ++ +. Save type definitions ++ +To avoid having to encode type definitions into base64 format to use directly with the Aura CLI, save them in a file. ++ +. Create ++ +Provision the GraphQL API, replacing the values in UPPERCASE with your own: ++ +[source, bash, indent=0] +---- +aura-cli data-api graphql create --name YOUR_FRIENDLY_NAME --instance-id YOUR_AURA_INSTANCE_ID --instance-username YOUR_AURA_INSTANCE_USER --instance-password YOUR_AURA_INSTANCE_PASSWORD --type-definitions-file FULL_PATH_TO_YOUR_TYPE_DEFS +---- ++ +The response shows information about the new GraphQL API. +Make sure you note the API Key and ID. ++ +. Check progress ++ +To see if the GraphQL API is ready to use, run the following command: ++ +[source, bash, indent=0] +---- +aura-cli data-api graphql get YOUR_GRAPHQL_API_ID --instance-id YOUR_AURA_INSTANCE_ID +---- + +If the status is "Ready", the API is ready to use. diff --git a/modules/ROOT/pages/aura-graphql/api-deletion.adoc b/modules/ROOT/pages/aura-graphql/api-deletion.adoc new file mode 100644 index 00000000..7415c162 --- /dev/null +++ b/modules/ROOT/pages/aura-graphql/api-deletion.adoc @@ -0,0 +1,59 @@ += Deleting a GraphQL API + +== Console + +. In Aura Console, select **Data API** from the left side navigation. ++ +. Locate the GraphQL API that you wish to delete and use the three dots icon, then **Delete**. ++ +Confirm the deletion by typing the name of the GraphQL API in the dialog and select **Delete** again. ++ +image::aura-graphql/delete/confirm-deletion.png[] + + +== Aura CLI + +Deletion of a GraphQL API using the Aura CLI requires: + +* The ID of the AuraDB the GraphQL API is being used with. +* The ID of GraphQL API. + +[CAUTION] +==== +The Aura CLI does not ask for confirmation and processes the command immediately. +==== + + +=== Looking up the IDs + +. Find the ID of the AuraDB. ++ +Display a list of AuraDBs in a table: ++ +[source, bash, indent=0] +---- +aura-cli instance list +---- +From the table, find the AuraDB that has the GraphQL API that you wish to change. +Make a note of its ID. ++ +. Find the GraphQL ID ++ +Using the AuraDB ID, list any GraphQL API that it may have: ++ +[source, bash, indent=0] +---- +aura-cli data-api graphql list --instance-id YOUR_AURA_INSTANCE_ID +---- ++ +From that table, locate the GraphQL API you want to modify and make a note of its ID. + + +=== Delete the GraphQL API + +Using both the AuraDB instance ID and the ID of the associated GraphQL API, you can now delete the GraphQL API itself: + +[source, bash, indent=0] +---- +aura-cli data-api graphql delete YOUR_GRAPHQL_DATA_API_ID --instance-id YOUR_AURA_INSTANCE_ID +---- diff --git a/modules/ROOT/pages/aura-graphql/api-update.adoc b/modules/ROOT/pages/aura-graphql/api-update.adoc new file mode 100644 index 00000000..b2dcb261 --- /dev/null +++ b/modules/ROOT/pages/aura-graphql/api-update.adoc @@ -0,0 +1,191 @@ += Updating a GraphQL API + +You can change the following configuration settings of an existing GraphQL API: + +* The friendly name of the GraphQL API. +* Username and/or password for the associated Aura instance. +* Type definitions. +* The authentication provider(s) used by the GraphQL API. +* The CORS policy used by the GraphQL API. + +== Console + +. In Aura Console, select **Data API** from the left side navigation. ++ +. Locate the GraphQL API that you wish to update and use the three dots icon, then **Edit**. ++ +Review and make changes to the configuration settings. +**Save** to persist your changes, or go **Back** to discard any changes made. + +It takes a few moments to apply the saved changes. +When the data API has a status of "Ready", the changes have been applied. + + +== Aura CLI + +There are three main commands used by the Aura CLI to modify a GraphQL API: + +. `update`: Modify the general settings of a GraphQL Data API. +. `cors-policy`: Change the Cross-Origin Resource Sharing (CORS) policy. +. `auth-provider`: Manage the authentication providers used by the GraphQL API. + + +To change the settings with the Aura CLI, it is first necessary to obtain: + +* The ID of the AuraDB the GraphQL API is being used with. +* The ID of GraphQL API. + +[CAUTION] +==== +The Aura CLI does not ask for confirmation and processes a command immediately. +==== + +=== Looking up the IDs + +. Find the ID of the AuraDB. ++ +Display a list of AuraDBs in a table: ++ +[source, bash, indent=0] +---- +aura-cli instance list +---- +From the table, find the AuraDB that has the GraphQL API that you wish to change. +Make a note of its ID. ++ +. Find the GraphQL ID ++ +Using the AuraDB ID, list any GraphQL API that it may have: ++ +[source, bash, indent=0] +---- +aura-cli data-api graphql list --instance-id YOUR_AURA_INSTANCE_ID +---- ++ +From that table, locate the GraphQL API you want to modify and make a note of its ID. + + +=== Reviewing the settings + +Before you make changes it is useful to review the current settings. +Using the IDs of both AuraDB and the GraphQL API, this is achieved with: + +[source, bash, indent=0] +---- +aura-cli data-api graphql get YOUR_GRAPHQL_API_ID --instance-id YOUR_AURA_INSTANCE_ID +---- + + +=== `update` + +The `update` command allows for modification of: + +* The GraphQL API friendly name. +* The username of the associated AuraDB. +* The password for the username of the associated AuraDB. +* The type definitions used by the GraphQL API. + +You can change multiple settings at once: + +[source, bash, indent=0] +---- +aura-cli data-api graphql update --instance-id +---- + +where `` is one or more from: + +* `--instance-password ` - The password of the instance this GraphQL Data API connects to. +* `--instance-username ` - The username of the instance this GraphQL Data API connects to. +* `--name ` - The name of the GraphQL Data API. +* `--type-definitions ` - The GraphQL type definitions. These must be Base64-encoded. +* `--type-definitions-file `- The path to a local GraphQL type definitions file, e.g. `path/to/typeDefs.graphql`. + + +=== `auth-provider` + +GraphQL for Neo4j AuraDB allows you to use an API key, a JWT token from an external identity provider or both for authentication and switch between them. +The authentication method is stored as an authentication provider. + +There are advantages and disadvantages to both types. +API keys are quickly set up but do not allow for access control and should not be used within a user-facing client application. +JWKS (JSON Web Key Sets) authentication providers require an external identity provider but allow for fine-grained rules around authentication and authorization as part of a GraphQL API type definitions. + +[CAUTION] +==== +If you use an API key authentication provider in a user-facing client application, you risk leaking the API key to your users. +This can give them full access to your GraphQL API. +We recommend you to use JWKS authentication providers in user-facing client applications. +==== + +- View the list of current authentication providers: ++ +[source, bash, indent=0] +---- +aura-cli data-api graphql auth-provider list --data-api-id YOUR_GRAPHQL_API_ID --instance-id YOUR_AURA_INSTANCE_ID +---- ++ +- Get the details of a specific authentication provider: ++ +[source, bash, indent=0] +---- +aura-cli data-api graphql auth-provider get YOUR_AUTH_PROVIDER_ID --data-api-id YOUR_GRAPHQL_API_ID --instance-id YOUR_AURA_INSTANCE_ID +---- ++ +- Add a new API key. + You can create a new API key and mark it as disabled to prevent its use. + To do that, add `--disabled` to the command. + It is only possible to enable the key via the Console. ++ +[source, bash, indent=0] +---- +aura-cli data-api graphql auth-provider create --name YOUR_FRIENDLY_NAME --type api-key --data-api-id YOUR_GRAPHQL_API_ID --instance-id YOUR_AURA_INSTANCE_ID +---- ++ +- Add a new JWKS. + You can create a new JWKS and mark it as disabled to prevent its use. + To do that, add `--disabled` to the command. + It is only possible to enable the key set using the Console. ++ +[source, bash, indent=0] +---- +aura-cli data-api graphql auth-provider create --name YOUR_FRIENDLY_NAME --url YOUR_URL_FOR_JWKS_VERIFICATION --type jwks --data-api-id YOUR_GRAPHQL_API_ID --instance-id YOUR_AURA_INSTANCE_ID +---- ++ +- Remove an existing authentication provider. + An authentication provider for a GraphQL API can be removed by deleting it. + At least one enabled authentication provider is required for a GraphQL API. ++ +[source, bash, indent=0] +---- +aura-cli data-api graphql auth-provider delete --name YOUR_FRIENDLY_NAME --type api-key --data-api-id YOUR_GRAPHQL_API_ID --instance-id YOUR_AURA_INSTANCE_ID +---- + + +=== `cors-policy` + +You can add or remove allowed origins for the CORS policy of the GraphQL API. + +- Display the existing allowed origins: ++ +[source, bash, indent=0] +---- +aura-cli data-api graphql get YOUR_GRAPHQL_API_ID --instance-id YOUR_AURA_INSTANCE_ID +---- ++ +- Add a new origin: ++ +[source, bash, indent=0] +---- +aura-cli data-api graphql cors-policy allowed-origin add ORIGIN --data-api-id YOUR_GRAPHQL_API_ID --instance-id YOUR_AURA_INSTANCE_ID +---- ++ +Adding several origins requires executing this command multiple times. ++ +- Remove an existing origin: ++ +[source, bash, indent=0] +---- +aura-cli data-api graphql cors-policy allowed-origin remove ORIGIN --data-api-id YOUR_GRAPHQL_API_ID --instance-id YOUR_AURA_INSTANCE_ID +---- ++ +Removing several origins requires executing this command multiple times. diff --git a/modules/ROOT/pages/aura-graphql/api-usage.adoc b/modules/ROOT/pages/aura-graphql/api-usage.adoc new file mode 100644 index 00000000..b84d73c9 --- /dev/null +++ b/modules/ROOT/pages/aura-graphql/api-usage.adoc @@ -0,0 +1,30 @@ += Using your GraphQL API + +== Querying your GraphQL API + +When the status for the GraphQL API is "Ready" you can send GraphQL requests to it. +As all requests are subject to authentication, you must include an API key or JWT token. + +=== With an API key authentication provider + +Add `x-api-key: YOUR_API_KEY` to the header of the request. +For example, with cURL: + +[source, bash, indent=0] +---- +curl --location --header 'Content-Type: application/json' --header 'x-api-key: ' --data '' +---- + +=== With a JWKS authentication provider + +Obtain a JWT from your identity provider. +Using the JWT, add `Authorization: Bearer ` to the headers of the request. + +For example, with cURL: + +[source, bash, indent=0] +---- +curl --location --header 'Authorization: Bearer '--header 'Content-Type: application/json --data '' +---- + + diff --git a/modules/ROOT/pages/aura-graphql/aura-cli-configuration.adoc b/modules/ROOT/pages/aura-graphql/aura-cli-configuration.adoc new file mode 100644 index 00000000..f0493193 --- /dev/null +++ b/modules/ROOT/pages/aura-graphql/aura-cli-configuration.adoc @@ -0,0 +1,148 @@ += Configuring the Aura CLI + +GraphQL for Neo4j AuraDB is managed using the Aura Console or the beta commands of the Aura CLI. +For the latter there are installation and configuration steps to be taken before you can use it. + + +== Obtain Aura API credentials + +The Aura CLI communicates with Neo4j AuraDB platform via an API. +To use the API, a set of credentials is required. +To get the credentials, follow these steps depending on which version of the console you are using. + +. Log in to the link:https://console.neo4j.io/[Neo4j Aura Console]. +. Navigate to the top right and select your account name, then **API keys** from the dropdown menu. ++ +image::aura-graphql/aura-cli/account-dropdown.png[] ++ +. The menu shows existing API keys if you already have any. ++ +image::aura-graphql/aura-cli/api-keys.png[] ++ +. Use **Create**, then enter a a name for the API key and confirm with **Create**. ++ +image::aura-graphql/aura-cli/api-keys-create.png[] ++ +. The client ID and client secret are displayed. + Be sure to record or save these as the client secret will not be shown again. ++ +image::aura-graphql/aura-cli/api-keys-created.png[] + + +== Install the Aura CLI + +. Navigate to link:https://github.com/neo4j/aura-cli/releases/tag/v1.1.0[https://github.com/neo4j/aura-cli/releases/tag/v1.1.0] in your browser. ++ +[NOTE] +==== +Use Aura CLI version 1.1.0 or higher for managing your GraphQL APIs. +==== ++ +. Download the compressed file that matches your system. Make a note of the folder where the file is located. +. After the file has been downloaded, extract the contents. +. Open a command prompt and move to the location where you extracted the files. +. Complete the installation by moving the aura-cli executable file into the file path. +.. Mac/Linux users: ++ +[source, bash, indent=0] +---- +sudo mv aura-cli /usr/local/bin +---- ++ +.. Windows users: ++ +[source, cmd, indent=0] +---- +move aura-cli c:\windows\system32 +---- ++ +. At the command prompt, type: ++ +[source, bash, indent=0] +---- +aura-cli -v +---- ++ +. You should see this: ++ +[source, bash, indent=0] +---- +aura version v1.1.0 +---- + +[NOTE] +==== +If you are using a Mac, you may receive a warning from Apple that aura-cli could not be verified. +If this happens, navigate to **System Settings**, then **Privacy & Security** on the left, and scroll down on the right. +Select **Open Anyway**. +This should not happen again. +The aura-cli has been through the Apple certification process but it can take time to trickle down through the Apple ecosystem. +==== + +== Configure the Aura CLI + +Configure the Aura CLI with the Aura API client ID and client secret you obtained in xref:#_obtain_aura_api_credentials[]. + +. On the command line, execute the following: ++ +[source, bash, indent=0] +---- +aura-cli credential add --name --client-id --client-secret +---- ++ +. To verify that the credentials are working, list your Aura instances: ++ +[source, bash, indent=0] +---- +aura-cli instance list +---- + + +=== Enable the beta commands + +Set the configuration option to make available the beta commands to use GraphQL for Neo4j AuraDB with the Aura CLI. + +. On the command line, execute the following: ++ +[source, bash, indent=0] +---- +aura-cli config set beta-enabled true +---- ++ +. Check if the commands are listed: ++ +[source, bash, indent=0] +---- +aura-cli data-api graphql +---- ++ +. You should see this: ++ +[source, bash, indent=0] +---- +Allows you to programmatically provision and manage your GraphQL APIs + +Usage: + aura-cli data-api graphql [command] + +Available Commands: + auth-provider Allows you to programmatically manage Authentication providers for a specific GraphQL Data API + cors-policy Allows you to manage the Cross-Origin Resource Sharing (CORS) policy for a specific GraphQL Data API + create Creates a new GraphQL Data API + delete Delete a GraphQL Data API + get Get details of a GraphQL Data API + list Returns a list of GraphQL Data APIs + pause Pause a GraphQL Data API + resume Resume a GraphQL Data API + update Edit a GraphQL Data API + +Flags: + -h, --help help for graphql + +Global Flags: + --auth-url string + --base-url string + --output string + +Use "aura-cli data-api graphql [command] --help" for more information about a command. +---- diff --git a/modules/ROOT/pages/aura-graphql/authentication-providers.adoc b/modules/ROOT/pages/aura-graphql/authentication-providers.adoc deleted file mode 100644 index fc364539..00000000 --- a/modules/ROOT/pages/aura-graphql/authentication-providers.adoc +++ /dev/null @@ -1,102 +0,0 @@ -[[auth-providers]] -= Authentication providers - -GraphQL for Neo4j AuraDB allows you to use an API key, JWT token from an external identity provider or both for authentication and switch between them as needed. -The authentication method is stored as an authentication provider. - -There are advantages and disadvantages to both types. -API keys are quickly set up but do not allow for access control and should not be used within a user-facing client application. -JWKS (JSON Web Key Sets) authentication providers require an external identity provider but do allow for fine-grained rules around authentication/authorization. - -[NOTE] -==== -`--data-api-id` is used with the `aura-cli` when working with authentication providers rather than `--graphql-api-id` as you might have expected. -Conceptually a GraphQL API is a type of data API and there may be other types in the future. -Using `--data-api-id` allows for flexibility for potential future development work in this area. -==== - -== Creating a JWKS authentication provider - -Before using JWKS authentication providers, you must set up and configure an identity provider that: - - * manages users and their credentials securely, - * issues JWTs to authenticated users - * hosts a JWKS endpoint that can be used to validate JWTs by the GraphQL API. - - There are several 3rd parties who provide this type of service, e.g. Ping, Okta, Auth0 and any of the main cloud service providers. - Configuration of identity providers is beyond the scope of this guide. - -If you do use a JWKS authentication provider, you can take advantage of fine-grained access controls using the xref:security/authentication.adoc[`@authentication`] and xref:security/authorization.adoc[`@authorization`] directives of GraphQL for Neo4j AuraDB. - -[NOTE] -==== -If you make use of `@authentication` or `@authorization` rules, they are also applied to requests made with API keys. -We do not currently support adding claims to API keys so it is unlikely they are able to meet the rules you specify. -==== - -The aura-cli is used to create a new JWKS authentication provider. -You will need the JWKS URL to do this along with the ID of the GraphQL API with its associated AuraDB ID. - -At a command prompt, type the following, swapping out the UPPERCASE values for your own: - -[source, bash, indent=0] ----- -aura-cli data-api graphql auth-provider create --data-api-id YOUR_GRAPHQL_DATA_API_ID --instance-id YOUR_AURA_INSTANCE_ID --name AUTH_PROVIDER_FRIENDLY_NAME --type jwks --url JWKS_URL ----- - -On success, the command responds with details about the newly created JWKS provider. - -== Creating an API Key Authentication Provider - -[WARNING] -==== -If you use an API key authentication provider in a user-facing client application, you risk leaking the API key to your users. -This can give them full access to your GraphQL API. -We recommend you to use JWKS authentication providers in user-facing client applications. -==== - -When a new GraphQL API is created via the aura-cli, an API key authentication provider is the default. -However, if you require a new one, the following command allows you to create a new API Key. - -At a command prompt, type the following, swapping out the UPPERCASE values for your own: - -[source, bash, indent=0] ----- -aura-cli data-api graphql auth-provider create --data-api-id YOUR_GRAPHQL_DATA_API_ID --instance-id YOUR_AURA_INSTANCE_ID --name AUTH_PROVIDER_FRIENDLY_NAME --type api-key ----- - -On success, the command will respond with details about the newly created API Key. - -[NOTE] -==== -Make sure to record the API key shown in the response as it will not be displayed again. -==== - -== Listing authentication providers - -To see the list of authentication providers for a given GraphQL API use the following, exchanging UPPERCASE values for your own. - -[source, bash, indent=0] ----- -aura-cli data-api graphql auth-provider list --data-api-id YOUR_GRAPHQL_DATA_API_ID --instance-id YOUR_AURA_INSTANCE_ID ----- - -== Deleting an authentication provider - -An authentication provider for a GraphQL API can be removed by deleting it. -At least one enabled authentication provider is required for a GraphQL API. - -. Find the API authentication provider ID. -+ -[source, bash, indent=0] ----- -aura-cli data-api graphql auth-provider list --data-api-id YOUR_GRAPHQL_DATA_API_ID --instance-id YOUR_AURA_INSTANCE_ID --output table ----- -+ -. From the table, locate the ID for the authentication provider that you wish to delete. -. Delete the API key provider with the following aura-cli statement. -+ -[source, bash, indent=0] ----- -aura-cli data-api graphql auth-provider delete AUTH-PROVIDER-ID --data-api-id YOUR_GRAPHQL_DATA_API_ID --instance-id YOUR_AURA_INSTANCE_ID ----- diff --git a/modules/ROOT/pages/aura-graphql/deploy-and-operate.adoc b/modules/ROOT/pages/aura-graphql/deploy-and-operate.adoc deleted file mode 100644 index db75c3b6..00000000 --- a/modules/ROOT/pages/aura-graphql/deploy-and-operate.adoc +++ /dev/null @@ -1,81 +0,0 @@ -= Deploy and operate - -== Deploy a GraphQL API - - -Before you deploy a GraphQL API, complete the steps in xref::/aura-graphql/prerequisites.adoc[Prerequisites]. -Make sure that you have: - -* The ID, username and password for the AuraDB. -* A file containing the type definitions. - -You are now ready to create the GraphQL API with the Aura CLI. -Substitute the values in `CAPITALS` to match your setup: - -[source, bash, indent=0] ----- -aura-cli data-api graphql create --name YOUR_FRIENDLY_NAME --instance-id YOUR_AURA_INSTANCE_ID --instance-username YOUR_AURA_INSTANCE_USER --instance-password YOUR_AURA_INSTANCE_PASSWORD --type-definitions-file -FULL_PATH_TO_YOUR_TYPE_DEFS --await ----- - -[NOTE] -==== -Make sure to record the API key shown in the response as it will not be displayed again. -If the API key is lost, a new one can be created by following the steps to create a new API key auth provider in xref::/aura-graphql/authentication-providers.adoc[Authentication providers]. -==== - -There are other items of note in the response: - -* `id`: unique identifier for the GraphQL API -* `status`: tells you if the GraphQL API is ready to receive requests -* `url`: the connection address to access the GraphQL API - -To check if the GraphQL API is ready for requests, use the Aura CLI again, changing `YOUR_AURA_INSTANCE_ID` for the ID of your aura instance. - -[source, bash, indent=0] ----- -aura-cli data-api graphql list --instance-id YOUR_AURA_INSTANCE_ID ----- - -When the status changes to `ready`, the GraphQL API is available for servicing requests. - -== Modifying an existing GraphQL API - -It is possible to change the configuration of an existing GraphQL API. -The following properties can be modified: - -* Friendly name of the GraphQL API -* Username and/or password for the associated Aura instance -* Type definitions - -To do this, use the Aura CLI update command which requires IDs of the GraphQL API and its linked AuraDB instance. -The format of this Aura CLI command is as follows: - -[source, bash, indent=0] ----- -aura-cli data-api graphql update YOUR_GRAPHQL_API_ID --instance-id YOUR_AURA_INSTANCE_ID ----- - -As the change takes a few moments to apply, check the status of the GraphQL API after performing this operation. -If the status is `updating` then the change is still being processed. -When the change is committed, the status will return to `ready`. - -Additionally, it is possible to modify the authentication providers of GraphQL APIs. -To learn more, see xref::/aura-graphql/authentication-providers.adoc[Authentication providers]. - -== Deleting a GraphQL API - -When you no longer require the GraphQL API then delete it by using the Aura CLI delete command. -This requires the Aura instance ID and the ID of the GraphQL API. - -The format of this command is as follows: - -[source, bash, indent=0] ----- -aura-cli data-api graphql delete YOUR_GRAPHQL_API_ID --instance-id YOUR_AURA_INSTANCE_ID ----- - -[CAUTION] -==== -There is no additional confirmation - the GraphQL API will start to be deleted as soon as you execute the command. -==== diff --git a/modules/ROOT/pages/aura-graphql/end-of-beta-phase.adoc b/modules/ROOT/pages/aura-graphql/end-of-beta-phase.adoc deleted file mode 100644 index 5b00402e..00000000 --- a/modules/ROOT/pages/aura-graphql/end-of-beta-phase.adoc +++ /dev/null @@ -1,140 +0,0 @@ -= End of beta phase - -The beta phase of GraphQL for Neo4j AuraDB will end on the 18th of April 2025. -To prevent data loss and wrap up your beta experience we suggest you take the following steps: - -* Backup GraphQL Data API configuration -* Remove the GraphQL Data API -* Provide feedback - -You are not required to take action. -However, any running GraphQL Data API will be terminated after the 18th of April, resulting in the loss of its configuration information including type definitions. - - -== Backup the GraphQL Data API configuration - -Backing up your GraphQL Data API configuration makes re-use much quicker if you decide to use this feature once it is released. -If you want to run your own GraphQL service instead, the backup might still be useful since it includes the type definitions which can be used for that purpose. - -There are two ways to perform a backup: - -* Manually copy them one by one from the Aura Console -* Using the Aura CLI to obtain everything in a single operation - - -=== Console - -If you want to retain only parts of the configuration, this is a quick method to do so. -If you are intent on backing up all of the configuration, use the xref:#_aura_cli[] instead. - -1. On Aura Console, select **Data API** from the left side navigation. -+ -image::aura-graphql/console_data_api_sidebar.png[] -+ -2. The table shows your GraphQL Data APIs. Use the three dots on the row with the GraphQL Data API that you wish to backup and select **Edit**. -+ -image::aura-graphql/console_data_api_edit_menu.png[] -+ -3. Expand each of the sections and then make a note of the setting or copy as necessary. -+ -image::aura-graphql/console_data_api_edit.png[] - - -=== Aura CLI - -This section assumes that you have configured the Aura CLI. -If you have not, follow the guidance provided in xref:aura-graphql/prerequisites.adoc#_install_and_configure_the_aura_cli[]. - - -1. Look up the Aura instance ID that the GraphQL API is being used with. -+ -[source, bash, indent=0] ----- -aura-cli instance list --output table ----- -+ - -2. From the displayed table, make a note of relevant Aura ID. Use this ID to obtain the ID of the GraphQL API whose configuration you want to back up. -+ -[source, bash, indent=0] ----- -aura-cli data-api graphql list --instance-id YOUR_AURA_INSTANCE_ID --output table ----- -+ - -3. Finally, obtain the configuration of the GraphQL API itself in JSON format. -+ -[source, bash, indent=0] ----- -aura-cli data-api graphql get YOUR_GRAPHQL_DATA_API_ID --instance-id YOUR_AURA_INSTANCE_ID ----- -+ -4. Save the output for future use. - -[NOTE] -==== -Type definitions are stored using Base64 encoding. -Decode them to plain text before using with other systems. -==== - - -== Removing the GraphQL Data API - -Remove the GraphQL Data API either via Aura Console or with the Aura CLI. - -[WARNING] -==== -Once the GraphQL Data API has been deleted, it cannot be recovered. -==== - - -=== Console - -1. In Aura Console, select **Data API** from the left side navigation. -+ -image::aura-graphql/console_data_api_sidebar.png[] -+ -2. The table contains your GraphQL Data APIs. Use the three dots on the row with the GraphQL Data API that you wish to remove and select **Delete**. -+ -image::aura-graphql/console_data_api_delete_menu.png[] -+ -3. Type in the name of your GraphQL API and confirm with **Delete**. -+ -image::aura-graphql/console_data_api_confirm_delete_menu.png[] - - -=== Aura CLI - -This section assumes that you have configured the Aura CLI. -If you have not, follow the guidance provided in xref:aura-graphql/prerequisites.adoc#_install_and_configure_the_aura_cli[]. - -1. Locate the Aura instance ID that the GraphQL API is being used with. -+ -[source, bash, indent=0] ----- -aura-cli instance list --output table ----- -+ -2. From the displayed table, make a note of the relevant Aura ID. Use the ID to obtain the ID of the GraphQL API whose configuration you want to back up. -+ -[source, bash, indent=0] ----- -aura-cli data-api graphql list --instance-id YOUR_AURA_INSTANCE_ID --output table ----- -+ -3. Delete the GraphQL API. -+ -[WARNING] -==== -The Aura CLI does not ask for confirmation and processes the command immediately. -==== -+ -[source, bash, indent=0] ----- -aura-cli data-api graphql delete YOUR_GRAPHQL_DATA_API_ID --instance-id YOUR_AURA_INSTANCE_ID --output table ----- - - -== Provide feedback - -Please consider taking a few moments to provide feedback either by creating an issue in our link:https://github.com/neo4j/graphql/issues/new/choose[GitHub repository] or using our #graphql channel on our link:https://discord.gg/M8mTADEJ[Discord Community] or our link:https://community.neo4j.com/c/drivers-stacks/graphql/33[forums]. diff --git a/modules/ROOT/pages/aura-graphql/index.adoc b/modules/ROOT/pages/aura-graphql/index.adoc index d4f6f1a9..ecde5947 100644 --- a/modules/ROOT/pages/aura-graphql/index.adoc +++ b/modules/ROOT/pages/aura-graphql/index.adoc @@ -1,16 +1,5 @@ -= GraphQL for Neo4j AuraDB Beta += GraphQL for Neo4j AuraDB -Welcome to the beta release of GraphQL for Neo4j AuraDB. - -Your feedback and insights help us refine and evolve the product and meet the needs of our users. - -The beta release is designed to give you a first look at GraphQL for Neo4j AuraDB. -You may encounter suboptimal behavior. - -You can help us get GraphQL for Neo4j AuraDB ready for production: - -- *Dive in*: Explore and test its features. -- *Test the product limits*: We'd rather discover weak areas at this stage. -- *Share your experience*: Tell us what works, what doesn't, and what you'd like to see in the future. -- *Provide feedback*: Use our `#graphql` channel on our link:https://discord.gg/M8mTADEJ[Discord Community], or our link:https://community.neo4j.com/c/drivers-stacks/graphql/33[forums] to report issues, suggest improvements, or ask questions. +Welcome to GraphQL for Neo4j AuraDB. +If you would like to provide feedback, use our `#graphql` channel on our link:https://discord.gg/M8mTADEJ[Discord Community], or our link:https://community.neo4j.com/c/drivers-stacks/graphql/33[forums] to report issues, suggest improvements, or ask questions. diff --git a/modules/ROOT/pages/aura-graphql/prerequisites.adoc b/modules/ROOT/pages/aura-graphql/prerequisites.adoc deleted file mode 100644 index b45a4b80..00000000 --- a/modules/ROOT/pages/aura-graphql/prerequisites.adoc +++ /dev/null @@ -1,211 +0,0 @@ -= Prerequisites - -The beta of GraphQL for Neo4j AuraDB is managed via the Aura CLI command line tool. -You must install and configure the Aura CLI for this purpose. -Future versions will be fully integrated with the Aura Console. - -== Before you start - -Using the GraphQL API during the Open Beta is free of charge. -Usage of the associated AuraDB instance will be charged as normal unless you're using Aura Pro Trials which is a zero-cost option. - -At the end of the beta period, all running GraphQL endpoints will be terminated in preparation for the full release. -We will send out a notification two weeks before they are terminated. - - -== Obtain Aura API credentials - -The Aura CLI communicates with Neo4j AuraDB platform via an API. -To use the API, a set of credentials is required. -To get the credentials, follow these steps depending on which version of the console you are using. - -=== New unified Aura Console experience - -1. Log in to the link:https://console.neo4j.io/[Neo4j Aura Console]. -2. Navigate to the top right where your account name is displayed and click the down arrow. -+ -image::aura-graphql/unified-console-home.png[] -+ -3. In the menu, click *API keys*. -+ -image::aura-graphql/unified-console-account-dropdown.png[] -+ -4. Click *Create*. -+ -image::aura-graphql/unified-console-api-keys.png[] -+ -5. In the pop-up window, enter a name for the API Key and click *Create*. -+ -image::aura-graphql/unified-console-create-api-key.png[] -+ -6. The client ID and client secret are displayed. Make a note as the client secret will not be shown again and you need both. If you download them, keep them safe. - -=== Aura Console classic - -1. Log in to the link:https://console.neo4j.io/[Neo4j Aura Console]. -2. Navigate to the top right where your account name is displayed and click the down arrow. -+ -image::aura-graphql/console-classic-home.png[] -+ -3. A menu with your account name is displayed. Click *Account Details*. -4. In the *Account Details* menu, click *Create* in the *Aura API* credentials section. -+ -image::aura-graphql/console-classic-api-keys.png[] -+ -5. In the pop-up window, enter a client name and click *Create*. -6. The newly created client ID and client secret are displayed. Make sure to securely save these as they are required to use the Aura CLI. - -== Install and configure the Aura CLI - -=== Installation - -. Navigate to link:https://github.com/neo4j/aura-cli/releases/tag/v1.1.0[https://github.com/neo4j/aura-cli/releases/tag/v1.1.0] in your browser. -+ -[NOTE] -==== -Use Aura CLI version 1.1.0 or higher for managing your GraphQL APIs. -==== -+ -. Download the compressed file that matches your system. Make a note of the folder where the file is located. -. After the file has been downloaded, extract the contents. -. Open a command prompt and move to the location where you extracted the files. -. Complete the installation by moving the aura-cli executable file into the file path. -.. Mac/Linux users: -+ -[source, bash, indent=0] ----- -sudo mv aura-cli /usr/local/bin ----- -+ -.. Windows users: -+ -[source, cmd, indent=0] ----- -move aura-cli c:\windows\system32 ----- -+ -. At the command prompt, type: -+ -[source, bash, indent=0] ----- -aura-cli -v ----- -+ -. You should see this: -+ -[source, bash, indent=0] ----- -aura version v1.1.0 ----- - -[NOTE] -==== -If you are using a Mac, you may receive a warning from Apple that aura-cli could not be verified. -If this happens, open *System Settings*, click *Privacy & Security* on the left, and scroll down on the right. -Click *Open Anyway*. -This should not happen again. -The aura-cli has been through the Apple certification process but it can take time to trickle down through the Apple ecosystem. -==== - -=== Add Aura API credentials - -Configure the Aura CLI with the Aura API client ID and client secret you obtained earlier. -The Aura CLI refers to these as credentials and it is possible to have several sets of credentials and then choose which one to use. - -. At the command prompt, enter the following, using your values for the items in CAPITALS: -+ -[source, bash, indent=0] ----- -aura-cli credential add --name YOUR_LABEL --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET ----- -+ -. To confirm the credentials are working, list your Aura instances: -+ -[source, bash, indent=0] ----- -aura-cli instance list --output table ----- - - -=== Set the beta flag - -Instruct the Aura CLI to make available the commands for the open beta. -This requires setting a configuration option. - -. At the command prompt, enter the following: -+ -[source, bash, indent=0] ----- -aura-cli config set beta-enabled true ----- -+ -. Check if the commands are listed for the open beta: -+ -[source, bash, indent=0] ----- -aura-cli data-api graphql ----- -+ -. You should see this: -+ -[source, bash, indent=0] ----- -Allows you to programmatically provision and manage your GraphQL APIs - -Usage: - aura-cli data-api graphql [command] - -Available Commands: - auth-provider Allows you to programmatically manage Authentication providers for a specific GraphQL Data API - cors-policy Allows you to manage the Cross-Origin Resource Sharing (CORS) policy for a specific GraphQL Data API - create Creates a new GraphQL Data API - delete Delete a GraphQL Data API - get Get details of a GraphQL Data API - list Returns a list of GraphQL Data APIs - pause Pause a GraphQL Data API - resume Resume a GraphQL Data API - update Edit a GraphQL Data API - -Flags: - -h, --help help for graphql - -Global Flags: - --auth-url string - --base-url string - --output string - -Use "aura-cli data-api graphql [command] --help" for more information about a command. ----- - -== Write GraphQL type definitions - -Before you create a GraphQL API for use with an Aura instance, you must create type definitions. - -If you already have type definitions from an existing GraphQL implementation these can be used. -However, you must deal with some exceptions. -The following are not currently supported: - -* The `@customResolver` and `@populatedBy` directives -* Subscriptions - -Using the link:https://graphql-toolbox.neo4j.io/[Neo4j GraphQL Toolbox] is an easy way to produce and try out type definitions. -Use of the Toolbox requires a connection to your Aura instance. - - -When your type definitions are ready, save them to a file. -They will be used with the Aura CLI to create the GraphQL API. - -== Select the AuraDB instance - -At the command prompt, type: - -[source, bash, indent=0] ----- -aura-cli instance list ----- - -Your AuraDB instances are displayed along with their IDs. -Make a note of the ID of the AuraDB instance that you will use with the GraphQL API. - -After choosing an AuraDB to use and obtaining its ID, you must also have its username and password to use for authentication. -For AuraDB, the username will likely be "neo4j" and the password has been shown when it was created. diff --git a/modules/ROOT/pages/aura-graphql/using-your-api.adoc b/modules/ROOT/pages/aura-graphql/using-your-api.adoc deleted file mode 100644 index 89fd1726..00000000 --- a/modules/ROOT/pages/aura-graphql/using-your-api.adoc +++ /dev/null @@ -1,60 +0,0 @@ -= Using your GraphQL API - -== Querying your GraphQL API - -When the status for the GraphQL API is "ready" you can send GraphQL requests to it. -As all requests are subject to authentication, you must include an API key or JWT token. - -=== With an API Key authentication provider - -Add `x-api-key: YOUR_API_KEY` to the header of the request. -For example, with cURL and replacing the UPPERCASE values with those of your own: - -[source, bash, indent=0] ----- -curl --location YOUR_GRAPHQL_API_URL --header 'Content-Type: application/json' --header 'x-api-key: YOUR_API_KEY' --data 'YOUR_GRAPHQL_QUERY' ----- - -=== With a JWKS authentication provider - -Obtain a JWT from your identity provider. -Using the JWT, add `Authorization: Bearer YOUR_JWT` to the headers of the request. - -For example, with cURL and replacing the UPPERCASE values with those of your own: - -[source, bash, indent=0] ----- -curl --location YOUR_GRAPHQL_API_URL --header 'Authorization: Bearer YOUR_JWT'--header 'Content-Type: application/json --data 'YOUR_GRAPHQL_QUERY' ----- - -== Querying your GraphQL API from a browser - -=== CORS Policy - -For security reasons, browsers restrict cross-origin requests to servers. -This means that by default, if you configure a web app to make a request to your GraphQL APIs from a browser, it will fail. -This is because your web app is hosted at a different origin than your GraphQL API. - -However, most modern browsers support Cross-Origin Resource Sharing (CORS). -This involves the browser sending a "preflight" request to the server to check that it will allow the actual request. -You can configure your GraphQL APIs to allow cross-origin requests from your web app by adding it to the list of allowed origins. -For example, if you expect requests to be made by a web app hosted at `https://example.com`, this should be added to the list of allowed origins for your GraphQL API. - -[NOTE] -==== -Only exact matches for allowed origins are supported - wildcards (*) will do not work. -==== - -Use the aura-cli and the following command, replacing the UPPERCASE values as required: - -[source, bash, indent=0] ----- -aura-cli data-api graphql cors-policy allowed-origin add NEW_ALLOWED_ORIGIN --data-api-id YOUR_GRAPHQL_API_ID --instance-id YOUR_AURA_INSTANCE_ID ----- - -Allowed origins that are no longer required can be removed with the following command, replacing the UPPERCASE values as required: - -[source, bash, indent=0] ----- -aura-cli data-api graphql cors-policy allowed-origin remove OLD_ALLOWED_ORIGIN --data-api-id YOUR_GRAPHQL_API_ID --instance-id YOUR_AURA_INSTANCE_ID -----