diff --git a/products/analytics/src/content/graphql-api/getting-started/authentication/api-key-auth.md b/products/analytics/src/content/graphql-api/getting-started/authentication/api-key-auth.md new file mode 100644 index 00000000000..fb804d88d76 --- /dev/null +++ b/products/analytics/src/content/graphql-api/getting-started/authentication/api-key-auth.md @@ -0,0 +1,43 @@ +--- +title: Authenticate with a Cloudflare API key +order: 20 +--- + +# Authenticate with a Cloudflare API key + +API keys are unique to each Cloudflare user and used only for authentication. An API key does not authorize access to accounts or zones. To ensure that the GraphQL Analytics API authenticates your queries, retrieve your Cloudflare Global API Key. + +* Learn how to [find your API Key](https://support.cloudflare.com/hc/articles/200167836) in the Cloudflare Dashboard +* Learn how to [retrieve your API Key](https://api.cloudflare.com/#getting-started-requests) using the Cloudflare API + +## Edit HTTP headers for GraphiQL authentication + +1. Launch _GraphiQL_ + +2. Click **Edit HTTP Headers** + ![ ](../../../static/images/GraphiQL-edit-http-headers.png) + The _Edit HTTP Headers_ window appears. + ![ ](../../../static/images/GraphiQL-edit-http-headers-window.png) + +3. Click **Add Header** + ![ ](../../../static/images/GraphiQL-add-header.png) + +4. Enter **X-AUTH-EMAIL** in the _Header name_ field and your email address registered with Cloudflare in the _Header value_ field, and click **Save** + +5. Click **Add Header** + +6. Enter **X-AUTH-KEY** in the _Header Name_ field, then paste your Global API Key in the _Header value_ field, and click **Save** + ![ ](../../../static/images/GraphiQL-edit-http-headers-complete.png) + +7. Click anywhere outside the _Edit HTTP Headers_ window in _GraphiQL_ to return to the _Untitled Query 1_ tab + +8. Enter `https://api.cloudflare.com/client/v4/graphql` in the _GraphQL Endpoint_ field + ![ ](../../../static/images/GraphiQL-response-pane.png) + + + +Now that you have configured authentication with a Cloudflare API key, you are ready to run queries using _GraphiQL_. diff --git a/products/analytics/src/content/graphql-api/getting-started/authentication/api-token-auth.md b/products/analytics/src/content/graphql-api/getting-started/authentication/api-token-auth.md new file mode 100644 index 00000000000..6c090e20385 --- /dev/null +++ b/products/analytics/src/content/graphql-api/getting-started/authentication/api-token-auth.md @@ -0,0 +1,103 @@ +--- +title: Configure an Analytics API token +order: 30 +--- + +# Configure an Analytics API token + +Cloudflare recommends API tokens as the preferred authentication method with Cloudflare APIs. This article walks through creating API tokens for authentication to the GraphQL Analytics API. + +For more detail on API tokens and the full range of supported options, see [_Creating API tokens_](https://developers.cloudflare.com/api/tokens/create). + +To create an API token for authentication to the GraphQL Analytics API, use this workflow: + +* [Access the Create API Token page](#access-the-create-api-token-page) +* [Configure a custom API token](#configure-a-custom-api-token) +* [Review and create your API token](#review-and-create-your-api-token) +* [Copy and test your API token](#copy-and-test-your-api-token) + +## Access the Create API Token page + +To access the **Create Custom Token** page, follow these steps: + +1. Log in to your Cloudflare account and select _My Profile_ from the user account drop-down list. + + ![User account drop-down list](../../../static/images/account-profile.png) + +1. In your user profile page, select the **API Tokens** tab. + +1. In the **API Tokens** page, click **Create Token**. + + ![API Tokens tab](../../../static/images/user-profile-api-tokens-tab.png) + + The **Create API Token** page displays. + + ![Create API Token page](../../../static/images/create-api-token-page-display.png) + +The next section of this walkthrough shows you how to [configure a custom token](#configure-a-custom-token) for access to the GraphQL Analytics API. + +## Configure a custom API token + +To configure a custom token, follow these steps: + +1. Click **Get started** in the **Custom token** section of the **Create API Token** page: + + ![Create API Token page](../../../static/images/create-api-token-get-started.png) + + The **Create Custom Token** page displays: + + ![Create Custom Token page](../../../static/images/create-custom-api-token.png) + +1. Use the **Token name** text input to enter a descriptive name for your token. + +1. To configure access to the GraphQL Analytics API, use the **Permissions** drop-down lists. To set permissions for the GraphQL Analytics API, select _Analytics_ from the second drop-down list. + + This example scopes zone-level permissions for read access to the Analytics API: + + ![Configure permissions](../../../static/images/create-custom-token-permissions.png) + +1. To configure the specific zones to which the token grants access, use the **Resources** drop-down lists. In this example, the token is set to grant access to all zones: + + ![Configure resources](../../../static/images/create-custom-token-zone-resources.png) + +1. [Optional] To restrict the API token to specific IP addresses, use the **IP Address Filtering** controls. + + ![Configure IP](../../../static/images/create-custom-token-ip-address-filtering.png) + +1. To define how long the token is valid, click the **TTL** (time-to-live) start/end date picker. + + ![Configure TTL](../../../static/images/create-custom-token-ttl.png) + +1. Click **Continue to summary**. + +The next section of this walk through shows you how to [review and test your API token](#review-and-test-your-api-token). + +## Review and create your API token + +Once you click _Continue to summary_, the **API Token Summary** page displays. + +Use the **API Token Summary** to confirm that you have scoped the API Token to the desired permissions and resources before creating it. + +![ ](../../../static/images/api-token-summary.png) + +Once you have validated your API token configuration, click **Create Token**. + +## Copy and test your API token + +When you create a new token, a confirmation page displays that includes your token and a custom `curl` command. + +![ ](../../../static/images/api-token-confirmation-page.png) + +To copy the token to your device's clipboard, click the **Copy** button. + + + +To test your token, copy the `curl` command and paste it into a terminal. + +When you have finished, click **View all API tokens**. diff --git a/products/analytics/src/content/graphql-api/getting-started/authentication/index.md b/products/analytics/src/content/graphql-api/getting-started/authentication/index.md new file mode 100644 index 00000000000..55f654849f7 --- /dev/null +++ b/products/analytics/src/content/graphql-api/getting-started/authentication/index.md @@ -0,0 +1,40 @@ +--- +title: Authentication +order: 10 +--- + +# Authentication + +Cloudflare separates service configuration by zone. When there are multiple accounts each with many zones, it is important to restrict GraphQL Analytics API access to only those account and zone resources that are relevant for the task at hand. + +To secure access your GraphQL Analytics data, use a Cloudflare API key or token to authenticate an API request. + +This table outlines the differences between Cloudflare API keys and tokens: + + + + + + + + + + + + + + + + + + + + +
Authentication MethodDescription
API Keys

Unique to each Cloudflare user and used only for authentication. API keys do not authorize access to accounts or zones.

+

Use the Global API Key for authentication. Only use the Origin CA Key when you create origin certificates through the API.

API TokensCloudflare recommends API Tokens as the preferred way to interact with Cloudflare APIs. You can configure the scope of tokens to limit access to account and zone resources, and you can define the Cloudflare APIs to which the token authorizes access.
+ + + +To find and retrieve API keys, as well as edit HTTP headers for authentication in GraphiQL, see [_Authenticate with a Cloudflare API key_](/graphql-api/getting-started/authentication/api-key-auth/). + +To create and configure GraphQL Analytics API tokens, see [_Configure an Analytics API token_](/graphql-api/getting-started/authentication/api-token-auth/). diff --git a/products/analytics/src/content/graphql-api/getting-started/index.md b/products/analytics/src/content/graphql-api/getting-started/index.md index eb540b3dc95..d4b472fe4c7 100644 --- a/products/analytics/src/content/graphql-api/getting-started/index.md +++ b/products/analytics/src/content/graphql-api/getting-started/index.md @@ -5,118 +5,9 @@ order: 10 # Getting started -This section describes setting up authentication for _GraphiQL_ and GraphQL Analytics API querying basics. +Use these articles to get started with the Cloudflare GraphQL Analytics API: -## Setting up authentication in _GraphiQL_ +* [_Authentication_](/graphql-api/getting-started/authentication) walks you through the options and the steps required to successfully set up your access to Cloudflare API. +* [_Querying basics_](/graphql-api/getting-started/querying-basics) brings you simple query examples for you to start exploring the GraphQl Analytics API. -To ensure that the GraphQL Analytics API authenticates your queries, retrieve your Cloudflare Global API Key. - -- Learn how to [find your API Key](https://support.cloudflare.com/hc/articles/200167836) in the Cloudflare Dashboard - -- Learn how to [retrieve your API Key](https://api.cloudflare.com/#getting-started-requests) using the Cloudflare API - -**To edit HTTP headers for authentication in _GraphiQL_:** - -1. Launch _GraphiQL_ - -2. Click **Edit HTTP Headers** - ![ ](../../static/images/GraphiQL-edit-http-headers.png) - The _Edit HTTP Headers_ window appears. - ![ ](../../static/images/GraphiQL-edit-http-headers-window.png) - -3. Click **Add Header** - ![ ](../../static/images/GraphiQL-add-header.png) - -4. Enter **X-AUTH-EMAIL** in the _Header name_ field and your email address registered with Cloudflare in the _Header value_ field, and click **Save** - -5. Click **Add Header** - -6. Enter **X-AUTH-KEY** in the _Header Name_ field, paste your Global API Key in the \_Header value \_field, and click **Save** - ![ ](../../static/images/GraphiQL-edit-http-headers-complete.png) - -7. Click anywhere outside the _Edit HTTP Headers_ window in _GraphiQL_ to return to the _Untitled Query 1_ tab - -8. Enter `https://api.cloudflare.com/client/v4/graphql` in the _GraphQL Endpoint_ field - ![ ](../../static/images/GraphiQL-response-pane.png) - -The right-side response pane is empty if you entered your information correctly. An error displays if there are problems with your header credentials. - -That's it! You’re ready to run queries using _GraphiQL_. - -## Querying basics - -GraphQL structures data as a graph. You can explore the edges of the graph (using queries) to get the data you need. This is an example query format: - -```javascript -viewer { - zones(filter:...) { - requests(filter:...) { - date, time, bytes,... - } - } -} -``` - -where `viewer` represents the initial node of the user running the query. - -The viewer can access one or more zones (domains) or accounts. Each zone or account contains various data sets, such as HTTP requests for a zone. There are numerous metrics and dimensions about requests, such as the the response bytes or the time at which the requests were received. You can apply filters at each node. - -This example query shows a range of GraphQL functionality. Two data sets for the specified zone are queried simultaneously, filters and aggregations are applied, and a limit is set on the number of records returned (note that the `limit` argument must be included and can be equal to up to 10,000). - -```javascript - -query { - viewer { - zones(filter: {zoneTag: ""}) { - httpRequests1mGroups(limit: 5, filter: { datetime_gt: "2019-02-01T04:00:00Z", datetime_lt: "2019-02-01T06:00:00Z"}) { - sum { - countryMap { - bytes - clientCountryName - } - } - dimensions { - date - datetime - } - } - firewallEventsAdaptiveGroups(limit: 10, filter: { datetime_gt: "2019-02-01T04:00:00Z", datetime_lt: "2019-02-01T06:00:00Z"}) { - count - dimensions { - clientCountryName - clientAsn - datetimeHour - } - } - } - } -} -``` - - - -How can you tell what data sets, metrics, dimensions, operators, and functions are available? One of the great features of a GraphQL API is that it offers "introspection": you can explore the graph (by making API calls) to see the available data sets, the fields and their types, and the operations you can perform. _GraphiQL_ users this functionality to provide a "Documentation Explorer" that you can use to understand the schema. Click on the _Docs_ link on the right-hand side and then drill down starting with `Query` and proceeding to `viewer` and then `zone`. Introspection is also used to provide query auto-complete and syntax validation. - -## Helpful Resources - -Handy links for setting up the GraphQL Analytics API and learning about GraphQL. - -### Cloudflare specifc - -- [Understanding the Cloudflare Dashboard](https://support.cloudflare.com/hc/en-us/articles/205075117-Understanding-the-Cloudflare-dashboard) (explains where to find your Zone ID and API Key) - -- [How to find your zoneTag using the API](https://api.cloudflare.com/#getting-started-resource-ids) - -### General info on the GraphQL framework - -- [How to use GraphQL (tutorials)](https://www.howtographql.com/) - -- [Thinking in Graphs](https://graphql.org/learn/thinking-in-graphs/) - -- [What data can you can query in the GraphQL type system (schemas)](https://graphql.org/learn/schema/) - -- [How to pass variables in GraphiQL (Medium article with quick tips)](https://medium.com/graphql-mastery/graphql-quick-tip-how-to-pass-variables-into-a-mutation-in-graphiql-23ecff4add57) +For examples of how to build your own GraphQL Analytics dashboard and query specific information, such as Firewall and Workers events, see [_Tutorials_](/graphql-api/tutorials). diff --git a/products/analytics/src/content/graphql-api/getting-started/querying-basics.md b/products/analytics/src/content/graphql-api/getting-started/querying-basics.md new file mode 100644 index 00000000000..d7224d06173 --- /dev/null +++ b/products/analytics/src/content/graphql-api/getting-started/querying-basics.md @@ -0,0 +1,77 @@ +--- +title: Querying basics +order: 20 +--- + +# Querying basics + +GraphQL structures data as a graph. You can explore the edges of the graph by using queries to get the data you need. This is an example query format: + +```code +viewer { + zones(filter:...) { + requests(filter:...) { + date, time, bytes,... + } + } +} +``` + + where the `viewer` represents the initial node of the user running the query. + +The viewer can access one or more zones (domains) or accounts. Each zone or account contains various data sets, such as HTTP requests for a zone. There are numerous metrics and dimensions about requests, such as the the response bytes or the time at which the requests were received. You can apply filters at each node. + +This example query shows a range of GraphQL functionality. Two data sets for the specified zone are queried simultaneously, filters and aggregations are applied, and a limit is set on the number of records returned (note that you must include the `limit` argument, which can be equal or up to 10,000). + +```code +query { + viewer { + zones(filter: {zoneTag: ""}) { + httpRequests1mGroups(limit: 5, filter: { datetime_gt: "2019-02-01T04:00:00Z", datetime_lt: "2019-02-01T06:00:00Z"}) { + sum { + countryMap { + bytes + clientCountryName + } + } + dimensions { + date + datetime + } + } + firewallEventsAdaptiveGroups(limit: 10, filter: { datetime_gt: "2019-02-01T04:00:00Z", datetime_lt: "2019-02-01T06:00:00Z"}) { + count + dimensions { + clientCountryName + clientAsn + datetimeHour + } + } + } + } +} +``` + + + +How can you tell what data sets, metrics, dimensions, operators, and functions are available? One of the great features of a GraphQL API is that it offers "introspection": you can explore the graph (by making API calls) to see the available data sets, the fields and their types, and the operations you can perform. _GraphiQL_ users this functionality to provide a "Documentation Explorer" that you can use to understand the schema. Click on the _Docs_ link on the right-hand side and then drill down starting with `Query` and proceeding to `viewer` and then `zone`. Introspection is also used to provide query auto-complete and syntax validation. + +## Helpful Resources + +Handy links for setting up the GraphQL Analytics API and learning about GraphQL. + +### Cloudflare specifc + +* [_Understanding the Cloudflare Dashboard_](https://support.cloudflare.com/hc/en-us/articles/205075117-Understanding-the-Cloudflare-dashboard) +* [_How to find your zoneTag using the API_](https://api.cloudflare.com/#getting-started-resource-ids) + +### General info on the GraphQL framework + +* [_How to use GraphQL (tutorials)_](https://www.howtographql.com/) +* [_Thinking in Graphs_](https://graphql.org/learn/thinking-in-graphs/) +* [_What data can you can query in the GraphQL type system (schemas)_](https://graphql.org/learn/schema/) +* [_How to pass variables in GraphiQL (Medium article with quick tips)_](https://medium.com/graphql-mastery/graphql-quick-tip-how-to-pass-variables-into-a-mutation-in-graphiql-23ecff4add57) diff --git a/products/analytics/src/content/graphql-api/index.md b/products/analytics/src/content/graphql-api/index.md index 7f7f3036f14..458f009a921 100644 --- a/products/analytics/src/content/graphql-api/index.md +++ b/products/analytics/src/content/graphql-api/index.md @@ -3,7 +3,7 @@ title: GraphQL Analytics API order: 1 --- -# GraphQL Analytics API +# GraphQl Analytics API The GraphQL Analytics API provides data regarding HTTP requests passing through Cloudflare’s network, as well as data from specific products, such as Firewall or Load Balancing. Network Analytics users also have access to packet-level data. Use the GraphQL Analytics API to select specific data sets and metrics of interest, filter and aggregate the data along various dimensions, and integrate the results with other applications. @@ -13,4 +13,4 @@ GraphQL models a business domain as a graph using a schema. In the schema, there ## Clients -We’re using [_GraphiQL_ ](https://electronjs.org/apps/graphiql)for our example GraphQL queries. There are many other popular open-source clients that you can find online, such [_Altair_ ](https://altair.sirmuel.design) and [_Insomnia_](https://insomnia.rest). You can also use _curl_. +We are using [_GraphiQL_](https://electronjs.org/apps/graphiql) for our example GraphQL queries. There are many other popular open-source clients that you can find online, such as [_Altair_](https://altair.sirmuel.design) and [_Insomnia_](https://insomnia.rest). Using `curl` is also a possibility. diff --git a/products/analytics/src/content/static/images/account-profile.png b/products/analytics/src/content/static/images/account-profile.png new file mode 100644 index 00000000000..7ba57ef991d Binary files /dev/null and b/products/analytics/src/content/static/images/account-profile.png differ diff --git a/products/analytics/src/content/static/images/api-token-confirmation-page.png b/products/analytics/src/content/static/images/api-token-confirmation-page.png new file mode 100644 index 00000000000..72eb5f28e95 Binary files /dev/null and b/products/analytics/src/content/static/images/api-token-confirmation-page.png differ diff --git a/products/analytics/src/content/static/images/api-token-created.png b/products/analytics/src/content/static/images/api-token-created.png new file mode 100644 index 00000000000..ee1d28ca30d Binary files /dev/null and b/products/analytics/src/content/static/images/api-token-created.png differ diff --git a/products/analytics/src/content/static/images/api-token-optional.png b/products/analytics/src/content/static/images/api-token-optional.png new file mode 100644 index 00000000000..a89310e1a32 Binary files /dev/null and b/products/analytics/src/content/static/images/api-token-optional.png differ diff --git a/products/analytics/src/content/static/images/api-token-permissions.png b/products/analytics/src/content/static/images/api-token-permissions.png new file mode 100644 index 00000000000..24893fa8d23 Binary files /dev/null and b/products/analytics/src/content/static/images/api-token-permissions.png differ diff --git a/products/analytics/src/content/static/images/api-token-section.png b/products/analytics/src/content/static/images/api-token-section.png new file mode 100644 index 00000000000..8ca3decb815 Binary files /dev/null and b/products/analytics/src/content/static/images/api-token-section.png differ diff --git a/products/analytics/src/content/static/images/api-token-summary.png b/products/analytics/src/content/static/images/api-token-summary.png new file mode 100644 index 00000000000..1cfcb8736ac Binary files /dev/null and b/products/analytics/src/content/static/images/api-token-summary.png differ diff --git a/products/analytics/src/content/static/images/create-api-token-get-started.png b/products/analytics/src/content/static/images/create-api-token-get-started.png new file mode 100644 index 00000000000..54741943907 Binary files /dev/null and b/products/analytics/src/content/static/images/create-api-token-get-started.png differ diff --git a/products/analytics/src/content/static/images/create-api-token-page-display.png b/products/analytics/src/content/static/images/create-api-token-page-display.png new file mode 100644 index 00000000000..69cdfcbb2ac Binary files /dev/null and b/products/analytics/src/content/static/images/create-api-token-page-display.png differ diff --git a/products/analytics/src/content/static/images/create-api-token-page.png b/products/analytics/src/content/static/images/create-api-token-page.png new file mode 100644 index 00000000000..da8d47d6c62 Binary files /dev/null and b/products/analytics/src/content/static/images/create-api-token-page.png differ diff --git a/products/analytics/src/content/static/images/create-custom-api-token.png b/products/analytics/src/content/static/images/create-custom-api-token.png new file mode 100644 index 00000000000..7a731680824 Binary files /dev/null and b/products/analytics/src/content/static/images/create-custom-api-token.png differ diff --git a/products/analytics/src/content/static/images/create-custom-token-ip-address-filtering.png b/products/analytics/src/content/static/images/create-custom-token-ip-address-filtering.png new file mode 100644 index 00000000000..5cb304c8d7f Binary files /dev/null and b/products/analytics/src/content/static/images/create-custom-token-ip-address-filtering.png differ diff --git a/products/analytics/src/content/static/images/create-custom-token-permissions.png b/products/analytics/src/content/static/images/create-custom-token-permissions.png new file mode 100644 index 00000000000..7f8fc7f9149 Binary files /dev/null and b/products/analytics/src/content/static/images/create-custom-token-permissions.png differ diff --git a/products/analytics/src/content/static/images/create-custom-token-ttl.png b/products/analytics/src/content/static/images/create-custom-token-ttl.png new file mode 100644 index 00000000000..38bbd0b5c85 Binary files /dev/null and b/products/analytics/src/content/static/images/create-custom-token-ttl.png differ diff --git a/products/analytics/src/content/static/images/create-custom-token-zone-resources.png b/products/analytics/src/content/static/images/create-custom-token-zone-resources.png new file mode 100644 index 00000000000..e7dcd1ada01 Binary files /dev/null and b/products/analytics/src/content/static/images/create-custom-token-zone-resources.png differ diff --git a/products/analytics/src/content/static/images/user-profile-api-tokens-tab.png b/products/analytics/src/content/static/images/user-profile-api-tokens-tab.png new file mode 100644 index 00000000000..a97655cf009 Binary files /dev/null and b/products/analytics/src/content/static/images/user-profile-api-tokens-tab.png differ