Accessing GraphQL

If you'd like to try GraphQL, you'll need the following prerequisites:

  1. You must be signed up for the Early Access Program.
  2. You'll need an OAuth token with the right scopes.
  3. You can optionally choose to have GraphiQL installed.

We'll walk you through the last two steps below.

Generating an OAuth token

To generate an OAuth token, follow the steps in our Creating an access token guide. The scopes you require depends on the type of data you're trying to request. For example, if you just need user data, you can select the User scopes; if you need access to repository information, you can select the appropriate Repository scopes.

If you'd like to match the behavior of the GraphQL Explorer, you can request the following scopes:

  • user
  • public_repo
  • repo
  • repo_deployment
  • repo:status
  • read:repo_hook
  • read:org
  • read:public_key
  • read:gpg_key

The GraphQL endpoint will notify you if a resource you require needs a specific scope.

Using GraphiQL

We recommend downloading and installing the GraphiQL app. This is the same editor that the GraphQL Explorer uses.

Once you have an OAuth token and GraphiQL, it's time to configure the app!

  1. Launch GraphiQL.
  2. In the upper-right portion of GraphiQL, click Edit HTTP Headers.
  3. Add a header with a key of Authorization and a value of Bearer <token>, where <token> is your generated OAuth token. graphiql headers
  4. To return to the editor, click anywhere outside of the Edit HTTP Headers modal.
  5. As a GraphQL Endpoint, enter https://api.github.com/graphql. Ensure that POST is selected from the dropdown menu.

To test your access, let's run a query about yourself:

query {
  viewer {
    login
  }
}

If everything worked correctly, this will display your login. You're all set to start making queries!

Using curl (or your own HTTP-speaking library)

You can also communicate with our GraphQL server using basic HTTP verbs.

To fetch the introspection query, make a GET request using your your OAuth token where token is your generated OAuth token. For example:

curl -H "Authorization: bearer token" https://api.github.com/graphql

You can make a GraphQL query by issuing a POST request with a JSON payload. The payload must have a string called query. For example:

curl -H "Authorization: bearer token" -X POST -d '
{
 "query": "query { viewer { login }}"
}
' https://api.github.com/graphql

Note: The string value of "query" must escape newline characters. A multi-line JSON string will not be parsed correctly.