How to authenticate using GraphQL Cookies and JWT

Updated Sep 11, 2026

Learn how to add login to a GraphQL API powered by Apollo: send credentials, return a JWT, store it in a cookie, and use that token for every later request.

~~~

In this tutorial I’ll explain how to handle a login mechanism for a GraphQL API using Apollo.

We’ll create a private area that depending on your user login will display different information.

In detail, these are the steps:

Create a login form on the client
Send the login data to the server
Authenticate the user and send a JWT back
Store the JWT in a cookie
Use the JWT for further requests to the GraphQL API

The code for this tutorial is available on GitHub at https://github.com/flaviocopes/apollo-graphql-client-server-authentication-jwt. The repo still shows older package names in places; the samples below use the current @apollo/client and @apollo/server APIs.

Let’s start.

I start up the client application

Scaffold a Vite React app, then install Apollo Client and a few helpers:

npm create vite@latest client -- --template react
cd client
npm install
npm install @apollo/client graphql js-cookie react-router-dom

We’re on React Router for page navigation. No Create React App, no @reach/router, no apollo-boost / react-apollo packages — those moved into @apollo/client.

Let’s start by creating the login form.

Create a Form.jsx file in the src folder, and add this content into it:

import { useState } from 'react'
import { useNavigate } from 'react-router-dom'

const url = 'http://localhost:3000/login'

const Form = () => {
  const [email, setEmail] = useState('')
  const [password, setPassword] = useState('')
  const navigate = useNavigate()

  const submitForm = (event) => {
    event.preventDefault()

    const options = {
      method: 'post',
      headers: {
        'Content-type': 'application/x-www-form-urlencoded; charset=UTF-8',
      },
      body: `email=${email}&password=${password}`,
    }

    fetch(url, options)
      .then((response) => {
        if (!response.ok) {
          if (response.status === 404) {
            alert('Email not found, please retry')
          }
          if (response.status === 401) {
            alert('Email and password do not match, please retry')
          }
        }
        return response
      })
      .then((response) => response.json())
      .then((data) => {
        if (data.success) {
          document.cookie = 'token=' + data.token
          navigate('/private-area')
        }
      })
  }

  return (
    <div>
      <form onSubmit={submitForm}>
        <p>
          Email:{' '}
          <input
            type="text"
            onChange={(event) => setEmail(event.target.value)}
          />
        </p>
        <p>
          Password:{' '}
          <input
            type="password"
            onChange={(event) => setPassword(event.target.value)}
          />
        </p>
        <p>
          <button type="submit">Login</button>
        </p>
      </form>
    </div>
  )
}

export default Form

Here I assume the server will run on localhost, on the HTTP protocol, on port 3000.

There’s no Apollo code here. Just a form and some code to register a new cookie when we get successfully authenticated.

Using the Fetch API, when the form is sent by the user I contact the server on the /login REST endpoint with a POST request.

When the server will confirm we are logged in, it will store the JWT token into a cookie, and it will navigate to the /private-area URL, which we haven’t built yet.

Add the form to the app

Let’s edit the main.jsx file of the app to use this component:

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { BrowserRouter, Routes, Route } from 'react-router-dom'
import Form from './Form.jsx'

createRoot(document.getElementById('root')).render(
  <StrictMode>
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<Form />} />
      </Routes>
    </BrowserRouter>
  </StrictMode>
)

The server side

Let’s switch server-side.

Create a server folder and run npm init -y to create a ready-to-go package.json file.

Now run

npm install express @apollo/server @as-integrations/express4 cors bcrypt jsonwebtoken graphql graphql-tag cookie-parser

@apollo/server replaces apollo-server-express. We mount it on Express with expressMiddleware from @as-integrations/express4 (use @as-integrations/express5 if you’re on Express 5).

Next, create an app.js file.

In here, we’re going to first handle the login process.

Let’s create some dummy data. One user:

const users = [
  {
    id: 1,
    name: 'Test user',
    email: 'your@email.com',
    password:
      '$2b$10$ahs7h0hNH8ffAVg6PwgovO3AVzn1izNFHn.su9gcJnUWUzb2Rcb2W', // = ssseeeecrreeet
  },
]

and some TODO items:

const todos = [
  {
    id: 1,
    user: 1,
    name: 'Do something',
  },
  {
    id: 2,
    user: 1,
    name: 'Do something else',
  },
  {
    id: 3,
    user: 2,
    name: 'Remember the milk',
  },
]

The first 2 of them are assigned to the user we just defined. The third item belongs to another user. Our goal is to log in the user, and show only the TODO items belonging to them.

The password hash, for the sake of the example, was generated by me manually using bcrypt.hash() and corresponds to the ssseeeecrreeet string. More info on bcrypt here. In practice you’ll store users and todos in a database, and password hashes are created automatically when users register.

Now, I want to handle the login process.

I load a bunch of libraries we’re going to use, and initialize Express to use CORS, so we can use it from our client app (as it’s on another port), and I add the middleware that parses urlencoded data:

const express = require('express')
const cors = require('cors')
const bcrypt = require('bcrypt')
const jwt = require('jsonwebtoken')
const app = express()
app.use(cors())
app.use(
  express.urlencoded({
    extended: true,
  })
)

Next I define a SECRET_KEY we’ll use for the JWT signing, and I define the /login POST endpoint handler. There’s an async keyword because we’re going to use await in the code. I extract the email and password fields from the request body, and I lookup the user in our users “database”.

If the user is not found by its email I send an error message back.

Next, I check if the password does not match the hash we have, and send an error message back if so.

If all goes well, I generate the token using the jwt.sign() call, passing the email and id as user data, and I send it to the client as part of the response.

(While debugging, you can paste the token into my JWT decoder to check the payload and expiry — it runs entirely in the browser.)

Here’s the code:

const SECRET_KEY = 'secret!'

app.post('/login', async (req, res) => {
  const { email, password } = req.body
  const theUser = users.find((user) => user.email === email)

  if (!theUser) {
    res.status(404).send({
      success: false,
      message: `Could not find account: ${email}`,
    })
    return
  }

  const match = await bcrypt.compare(password, theUser.password)
  if (!match) {
    //return error to user to let them know the password is incorrect
    res.status(401).send({
      success: false,
      message: 'Incorrect credentials',
    })
    return
  }

  const token = jwt.sign(
    { email: theUser.email, id: theUser.id },
    SECRET_KEY
  )

  res.send({
    success: true,
    token: token,
  })
})

We’ll start listening after Apollo is wired up. Keep reading.

The private area

At this point client-side I add the token to the cookies and moves to the /private-area URL.

What’s in that URL? Nothing! Let’s add a component to handle that, in src/PrivateArea.jsx:

const PrivateArea = () => {
  return <div>Private area!</div>
}

export default PrivateArea

In main.jsx, we can add this to the app:

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { BrowserRouter, Routes, Route } from 'react-router-dom'
import Form from './Form.jsx'
import PrivateArea from './PrivateArea.jsx'

createRoot(document.getElementById('root')).render(
  <StrictMode>
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<Form />} />
        <Route path="/private-area" element={<PrivateArea />} />
      </Routes>
    </BrowserRouter>
  </StrictMode>
)

I use the nice js-cookie library to work easily with cookies. Using it I check if there’s the token in the cookies. If not, just go back to the login form:

import { useEffect } from 'react'
import Cookies from 'js-cookie'
import { useNavigate } from 'react-router-dom'

const PrivateArea = () => {
  const navigate = useNavigate()

  useEffect(() => {
    if (!Cookies.get('token')) {
      navigate('/')
    }
  }, [navigate])

  return <div>Private area!</div>
}

export default PrivateArea

Now in theory we’re all good to go and use the GraphQL API! But we have no such thing yet. Let’s make that thing.

The GraphQL API

Server-side I do everything in a single file. It’s not that big, as we have little things in place.

I add this near the top of the file:

const { ApolloServer } = require('@apollo/server')
const { expressMiddleware } = require('@as-integrations/express4')
const { GraphQLError } = require('graphql')
const gql = require('graphql-tag')

which gives us all we need to make the Apollo GraphQL server.

I need to define 3 things:

the GraphQL schema
resolvers
the context

Here’s the schema. I define the User type, which represents what we have in our users object. Then the Todo type, and finally the Query type, which sets what we can directly query: the list of todos.

const typeDefs = gql`
  type User {
    id: ID!
    email: String!
    name: String!
    password: String!
  }

  type Todo {
    id: ID!
    user: Int!
    name: String!
  }

  type Query {
    todos: [Todo]
  }
`

The Query type has one entry, and we need to define a resolver for it. Here it is:

const resolvers = {
  Query: {
    todos: (root, args, context) => {
      return todos.filter((todo) => todo.user === context.id)
    },
  },
}

Then the context, where we basically verify the token and error out if invalid, and we get the id and email values from it. This is how we know who is talking to the API:

const context = async ({ req }) => {
  const token = req.headers.authorization || ''

  try {
    const { id, email } = jwt.verify(token.split(' ')[1], SECRET_KEY)
    return { id, email }
  } catch (e) {
    throw new GraphQLError(
      'Authentication token is invalid, please log in',
      {
        extensions: { code: 'UNAUTHENTICATED' },
      }
    )
  }
}

The id and email values are now available inside our resolver(s). That’s where the context.id value we use above comes from.

We need to add Apollo to Express as middleware now, and the server side part is finished!

async function start() {
  const server = new ApolloServer({ typeDefs, resolvers })
  await server.start()

  app.use(
    '/graphql',
    cors(),
    express.json(),
    expressMiddleware(server, { context })
  )

  app.listen(3000, () => console.log('Server listening on port 3000'))
}

start()

The Apollo Client

We are ready to initialize our Apollo Client now!

In the client-side main.jsx file I add those imports:

import {
  ApolloClient,
  InMemoryCache,
  ApolloProvider,
  createHttpLink,
} from '@apollo/client'
import { setContext } from '@apollo/client/link/context'
import Cookies from 'js-cookie'

I initialize an HttpLink object that points to the GraphQL API server, listening on port 3000 of localhost, on the /graphql endpoint, and use that to set up the ApolloClient object.

An HttpLink provides us a way to describe how we want to get the result of a GraphQL operation, and what we want to do with the response.

const httpLink = createHttpLink({ uri: 'http://localhost:3000/graphql' })

const authLink = setContext((_, { headers }) => {
  const token = Cookies.get('token')

  return {
    headers: {
      ...headers,
      authorization: `Bearer ${token}`,
    },
  }
})

const client = new ApolloClient({
  link: authLink.concat(httpLink),
  cache: new InMemoryCache(),
})

and finally I use the ApolloProvider component we imported as a parent component and wrap everything in the app we defined. In this way we can access the client in any of our child components. In particular the PrivateArea one, very soon!

createRoot(document.getElementById('root')).render(
  <StrictMode>
    <ApolloProvider client={client}>
      <BrowserRouter>
        <Routes>
          <Route path="/" element={<Form />} />
          <Route path="/private-area" element={<PrivateArea />} />
        </Routes>
      </BrowserRouter>
    </ApolloProvider>
  </StrictMode>
)

The private area

So we’re at the last step. Now we can finally perform our GraphQL query!

Here’s what we have now:

import { useEffect } from 'react'
import Cookies from 'js-cookie'
import { useNavigate } from 'react-router-dom'

const PrivateArea = () => {
  const navigate = useNavigate()

  useEffect(() => {
    if (!Cookies.get('token')) {
      navigate('/')
    }
  }, [navigate])

  return <div>Private area!</div>
}

export default PrivateArea

I’m going to import gql and useQuery from @apollo/client:

import { gql, useQuery } from '@apollo/client'

The old render-prop <Query> component from react-apollo is gone. Use the useQuery hook instead:

const GET_TODOS = gql`
  {
    todos {
      id
      name
    }
  }
`

const PrivateArea = () => {
  const navigate = useNavigate()
  const { loading, error, data } = useQuery(GET_TODOS)

  useEffect(() => {
    if (!Cookies.get('token')) {
      navigate('/')
    }
  }, [navigate])

  useEffect(() => {
    if (error) {
      navigate('/')
    }
  }, [error, navigate])

  if (loading) return <p>Loading...</p>
  if (error) return <p></p>

  return (
    <div>
      <ul>
        {data.todos.map((item) => (
          <li key={item.id}>{item.name}</li>
        ))}
      </ul>
    </div>
  )
}

While the data is not available yet, loading is true and we can add a message to the user. If there’s any error we send the user back to login. Otherwise we get our TO-DO items in the data object and we can iterate over them.

Now that things are working, I want to change a little bit how the code works and add the use of HTTPOnly cookies. This special kind of cookie is more secure because we can’t access it using JavaScript, and as such it can’t be stolen by 3rd part scripts and used as a target for attacks.

Things are a bit more complex now so I added this at the bottom.

All the code is available on GitHub at https://github.com/flaviocopes/apollo-graphql-client-server-authentication-jwt and all I described up to now is available in this commit.

The code for this last part is available in this separate commit.

First, in the client, in Form.jsx, instead of adding the token to a cookie, I add a signedin cookie.

Remove this

document.cookie = 'token=' + data.token

and add

document.cookie = 'signedin=true'

Next, in the fetch options we must add

credentials: 'include'

otherwise fetch won’t store in the browser the cookies it gets back from the server.

Now in the PrivateArea.jsx file we don’t check for the token cookie, but for the signedin cookie:

Remove

if (!Cookies.get('token')) {

and add

if (!Cookies.get('signedin')) {

Let’s go to the server part.

First install the cookie-parser library with npm install cookie-parser and instead of sending back the token to the client:

res.send({
  success: true,
  token: token,
})

Only send this:

res.send({
  success: true,
})

We send the JWT token to the user as an HTTPOnly cookie:

res.cookie('jwt', token, {
  httpOnly: true,
  //secure: true, //on HTTPS
  //domain: 'example.com', //set your domain
})

(in production set the secure option on HTTPS and also the domain)

Next we need to set the CORS middleware to use cookies, too. Otherwise things will break very soon when we manage the GraphQL data, as cookies just disappear.

Change

app.use(cors())

with

const corsOptions = {
  origin: 'http://localhost:5173', // Vite default; change with your own client URL
  credentials: true,
}

app.use(cors(corsOptions))
app.use(cookieParser())

Back to the client, in main.jsx we tell Apollo Client to include credentials (cookies) in its requests. Switch:

const httpLink = createHttpLink({ uri: 'http://localhost:3000/graphql' })

with

const httpLink = createHttpLink({
  uri: 'http://localhost:3000/graphql',
  credentials: 'include',
})

and remove the authLink definition altogether:

const authLink = setContext((_, { headers }) => {
  const token = Cookies.get('token')

  return {
    headers: {
      ...headers,
      authorization: `Bearer ${token}`,
    },
  }
})

as we don’t need it any more. We’ll just pass httpLink to new ApolloClient(), since we don’t need more customized authentication stuff:

const client = new ApolloClient({
  link: httpLink,
  cache: new InMemoryCache(),
})

Back to the server for the last piece of the puzzle! In the context function definition, change

const token = req.headers.authorization || ''

with

const token = req.cookies['jwt'] || ''

and verify the cookie value directly (no Bearer split):

const { id, email } = jwt.verify(token, SECRET_KEY)

When you mount Apollo, keep CORS under your control (the Express cors middleware above), and pass the same options into expressMiddleware if you need path-scoped CORS:

app.use(
  '/graphql',
  cors(corsOptions),
  express.json(),
  expressMiddleware(server, { context })
)

Tagged: GraphQL · All topics

Follow @flaviocopes

Want me to talk about your product? You can sponsor this site.

~~~

I start up the client application

The login form

Add the form to the app

The server side

Handle the login process

The private area

The GraphQL API

The Apollo Client

The private area

Use an HttpOnly cookie for better security