Technical Docs


Suggestic supported authentication methods
Our GraphQL API currently supports 2 authentication methods that you can use depending on your case and needs, JWT Authentication and Basic API Token Authentication.

JWT Authentication

Use JWT to implement the client-side authentication system only
This method requires a valid user and password and returns a JWT that can be used to consume the GraphQL API.
Once this request is sent, the following information is displayed:
"email": "[email protected]",
"name": "lili",
"phone": "",
"user_id": "<user_id>",
"is_premium": false,
"birthdate": null,
"avatar": null,
"token": "<token>",
"refresh_token": "<refresh_token>",
"hashed_email": "59184e9bf7b070d500629ae7410aa1bce18ef6bf98655af15dbadadb58e1f137",
"program_id": "<program_id>",
"show_program_view": true,
"transaction_provider": "",
"transaction_duration": "",
"transaction_price": 0,
"profile_id": "<profile_id>"

How to use a Bearer Authentication within graphQL

Once you log in, open your Grapqhl Playground; in the authentication section, add the following header
"Authorization": "Bearer <insert_your_token_here>"
When a JWT authentication is used in GraphQL, it is not required to add the sg-user header.
For example:
The following query retrieves the information of a meal plan by giving the bearer token

cURL Request with Bearer token

The bearer token is sent to the server with the 'Authorization: Bearer {token}' authorization header.
In the following example, we are getting the shopping list request.
cURL Request
curl -XPOST '' \
-H 'Authorization: Bearer <insert_your_bearer_token_here>' \
-H 'Content-Type: application/json' \
--data-raw '{"query":"{\n shoppingList { edges {node {ingredientLine quantity aisleName recipeName isDone unit databaseId errors } } }}"}'

Refresh Token

For security purposes, the access token expires after 2 hours. Once expired, your client applications may use a refresh token to “refresh” the access token.
You may obtain a refresh token using the login mutation.
mutation {
login(userId: "<USERID>") {

Using JWT without a user's password

If you are not using Suggestic as your identity provider, you can still obtain a JWT from the API using the login mutation. This should be done from your backend using the standard API token authentication.
mutation {
login(userId: "<USERID>") {
In this case, you can expect your authentication flow to be as follows:
  • Authenticate the user on your frontend with your implementation.
  • Request a JWT on your backend, on behalf of the user, via a request to the Suggestic API using your API key and the user’s ID.
  • Pass the JWT to your frontend.
  • The frontend then uses that JWT for all future Suggestic API calls.

API Token Authentication

Use the API authorization token provided on server-side applications only
Use this authentication method to access the API "on behalf" of your users.
To use this method, you require a valid API token and a user id. Add these to a custom HTTP Header, as shown below.
Do not use your API token on client-side authentication. If so, please request a new token.

Clients/Partners API Token

Partners/clients which have an isolated database will need to authenticate by using a different HTTP header named Suggestic-Partner. Use it as it is explained below:
HTTP Header
"Authorization": "Token <TOKEN>",


cURL Example

To query GraphQL using cURL, make a POST request with a JSON payload. The payload must contain a string called query:
curl '' -XPOST \
-H 'Content-Type: application/json' \
-H 'Authorization: Token 7b9f6fd852faba099be1984c97124b7f8d776f26' \
-H 'sg-user: e084268c-5487-4f35-9d74-9ce41de3992b' \
-d '{"query": "{ myProfile { id programName } }"}'
"data": {
"myProfile": {
"id": "e084268c-5487-4f35-9d74-9ce41de3992b",
"programName": "Anti-Inflammatory Diet"
Note: The string value of "query" must escape newline characters, or the schema will not parse it correctly. For the POST body, use outer double quotes and escaped inner double quotes.
If you need to use your partner/client header, use the following cURL
curl -XPOST '' \
-H 'Authorization: Token <API-Token>' \
-H 'SG-User: <user-id>' \
-H 'Suggestic-Partner: <PARTNER-SLUG>' \
-H 'Content-Type: application/json' \

Python Example

import requests
# HTTP Headers including sg-user for especific user context
headers = {
"Authorization": "Token 7b9f6fd852faba099be1984c97124b7f8d776f26",
"sg-user": "e084268c-5487-4f35-9d74-9ce41de3992b"
# GraphQL query
query = """{ myProfile { id programName } }"""
# Make request
r =
json={"query": query}
# print json response
If you need to use your partner/client header, replace sg-user with the Suggestic-Partner information