cloudflare · paulo-docforce · Oct 27, 2020 · Nov 4, 2020
@@ -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)
+
+<Aside type='note' header='Note'>
+
+The right-side response pane is empty when you enter your information correctly. An error displays when there are problems with your header credentials.
+
+</Aside>
+
+Now that you have configured authentication with a Cloudflare API key, you are ready to run queries using _GraphiQL_.
@@ -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.  
+
+<Aside type='note' header='Note'>
+
+The confirmation page is the only time that you can see the token, so make sure you store it safely, since anyone who has token can use it to access your data.
+
+If you lose the secret, you can [regenerate the token from the API Tokens page](https://support.cloudflare.com/hc/en-us/articles/200167836-Managing-API-Tokens-and-Keys#12345681), so that you do not have to configure all the permissions again.
+
+</Aside>
+
+To test your token, copy the `curl` command and paste it into a terminal.
+
+When you have finished, click **View all API tokens**.
@@ -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:
+
+<TableWrap>
+
+<table>
+  <thead>
+      <tr>
+          <th>Authentication Method</th>
+          <th>Description</th>
+      </tr>
+  </thead>
+  <tbody>
+      <tr>
+        <td><a href='https://developers.cloudflare.com/api/keys'>API Keys</a></td>
+        <td><p>Unique to each Cloudflare user and used only for authentication. API keys do not authorize access to accounts or zones.</p>
+        <p>Use the Global API Key for authentication. Only use the Origin CA Key when you create origin certificates through the API.</p></td>
+      </tr>
+      <tr>
+        <td><a href='https://developers.cloudflare.com/api/tokens/create'>API Tokens</a></td>
+        <td>Cloudflare 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.</td>
+      </tr>
+  </tbody>
+</table>
+
+</TableWrap>
+
+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/).
@@ -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: "<your zone ID>"}) {
-      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
-        }
-      }
-    }
-  }
-}
-```
-
-<Aside type="note" header="Note">
-
-This is only an example. You must specify the `zoneTag` for your domain. Your Cloudflare dashboard lists your Zone ID (`zoneTag`) on the _Overview_ page.
-
-</Aside>
-
-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).
@@ -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: "<your zone ID>"}) {
+      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
+        }
+      }
+    }
+  }
+}
+```
+
+<Aside type='note' header='Note'>
+
+This is only an example. You must specify the <code>zoneTag</code> for your domain. Your Cloudflare dashboard lists your Zone ID (<code>zoneTag</code>) on the <em>Overview</em> page.
+
+</Aside>
+
+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)