GraphcoolDocs
FAQ

Authentication Tokens

Last updated a day ago Edit this page

GraphQL requests are authenticated using an authentication token. For server-side requests, permanent authentication tokens can be used.

#Overview

Requests to your CRUD API (or the System API) are authenticated using authentication tokens that are attached to the Authorization header of the request. Graphcool uses JWT (JSON Web Tokens) as a token format.

Grpahcool offers several types of authentication tokens:

  • Node tokens: A node token is associated with a specific node in your database (no matter which type) and has a certain validity duration (the default is 30 days). They can be issued using the generateNodeToken(nodeId: string, typeName: string, payload?: ScalarObject) function in graphcool-lib or by directly calling the generateNodeToken-mutation of the Graphcool System API for which different validity durations can be specified.
  • Root tokens (previously called permanent access tokens (PATs)): A root token grants full access to all API operations. There are two kinds of root tokens:

    • Regular: Useful for scripts or other applications that need access to your API. You can manage them in your service settings or using the CLI.
    • Temporary: Every function receives a temporary root token as an input argument so you are able to run queries and mutation against your API without additional authentication overhead.
  • Platform tokens: A platform token authenticates requests against the Graphcool System API. You can obtain it by logging in to the Graphcool platform. After a successful login, the token will be stored in the global .graphcoolrc in your home directory and used by the CLI for any platform requests that require authentication.
  • Cluster secrets: When deploying a Graphcool instance with Docker, a cluster secret (also sometimes called master token) is required to manage the cluster.

#Authenticating a request

Authentication tokens need to be passed in the Authorization field of the HTTP header:

1
Authorization: Bearer <authentication token>

Here is a sample CURL request that carries the Authorization field:

curl 'https://api.graph.cool/simple/v1/cj8sj0xes01o8017095vw1tw0'\
   -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MTEwMDEzNTIsImlhdCI6MTUwODQwOTM1MiwicHJvamVjdElkIjoiY2o4c2oweGVzMDFvODAxNzA5NXZ3MXR3MCIsInVzZXJJZCI6ImNqOHliemQ5ZjFmajUwMTMwaHh4ZTZreHUiLCJtb2RlbE5hbWUiOiJVc2VyIn0.h36n5cPk4glRptEO882Ngf-0u_OWPquGZMW0F94j_8M'\
   -H 'Content-Type: application/json'\
   -d '{"query":"{ loggedInUser { id } }"}'

If a request to your endpoint contains a valid authentication token, it is considered authenticated with regards to the permission system. A request with an invalid authentication token in its header is treated as if the token would not be passed at all.

#Node tokens

A node token always needs to be associated with a particular node (often of type User or something similar) in your database. When the token is contained in the Authorization header of a request that is executed against your service's API, it means that the request is made on behalf of the node that it is associated with.

#Generating a node token with graphcool-lib

You can use the generateAuthToken function in graphcool-lib to generate a new node token.

Here is how it works:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
const fromEvent = require('graphcool-lib').fromEvent

module.exports = event => {

  const nodeId = ... // e.g. 

  const graphcool = fromEvent(event)
  const validityDuration = 864000 // 864000 seconds are 10 days

  // validityDuration is an optional argument, the default is 30 days 
  const node = graphcool.generateNodeToken(nodeId, 'User', validityDuration)

  // ...
}

To see fully implemented authentication flows, you can review the predefined authentication templates.

#Generating a node token with the Graphcool System API

Another option to generate node tokens is by directly talking to the Graphcool System API.

Here is a sample mutation to generate a node token for a User model type:

1
2
3
4
5
6
7
8
9
10
11
12
mutation GenerateRootToken($rootToken: String!, $serviceId: ID!, $nodeId: ID!) {
  generateNodeToken(input: {
    rootToken: $rootToken,
    serviceId: $serviceId,
    nodeId: $nodeId,
    modelName: "User",
    expirationInSeconds: 864000, # 864000 seconds are 10 days (default is 30)
    clientMutationId: ""
  }) {
    token
  }
}

#Root tokens

Be very careful where you use the root tokens. Everyone with a root token has full read and write access to your data, so you should never include them anywhere client-side, like on a public website or a mobile app.

#Creating a regular root token

Regular root tokens are created with the Graphcool CLI and the service definition.

To create a new root token, you need to add a new entry to the rootTokens list in your graphcool.yml. The entry defines the name of the root token. Here is an example where a service has two root tokens, called myToken1 and myToken2:

1
2
3
rootTokens:
  - myToken1
  - myToken2

After modifying the rootTokens list, you need to apply the changes by invoking the graphcool deploy command.

Note: In the case of legacy projects, root tokens are managed through the Graphcool Console - not the CLI. To create a new root token in the Console, navigate to your project settings and select the Authentication-tab. Then click the add permanent access token, set the name for the token and confirm.

#Obtaining a regular root token

When your service is deployed, the corresponding target will be associated with the root tokens defined in graphcool.yml.

You can obtain the value of the root token using the graphcool root-token command:

graphcool root-token --token myToken1

If you don't pass the --token option to the command, it will simply print the names of all the root tokens associated with this target.

#Using a temporary root token inside functions

Root tokens are particularly useful inside functions to authenticate requests against the service's API. The input event for functions carries a temporary root token that you can access as follows:

1
2
3
4
5
6
7
module.exports = function(event) {

  const rootToken = event.context.graphcool.pat

  // ...

}

pat stands for permanent access token which is the deprecated term for a root token.

When using the fromEvent function from graphcool-lib to create a GraphQL client for your service's API, the root token will automatically be set in the Authorization header.

Was this page helpful?