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.

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.

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.

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.

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.

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 graphcooldeploy 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.