2. Authentication & authorization

2.1 Which authentication method does DE use and how do I refresh tokens?

We use JWT authentication method.

Authenticate with login(email, password) to receive:

token (access token, JWT)
refreshToken
expiresIn (seconds)

mutation Login($email: String!, $password: String!) {
    login(email: $email, password: $password) {
        token
        refreshToken
        expiresIn
    }
}

Incorrect common errors:

Invalid credentials. Check that your credentials are correct.

{
  "errors": [
    {
      "message": "Incorrect email or password",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "login"
      ],
      "extensions": {
        "code": "INTERNAL_SERVER_ERROR"
      }
    }
  ],
  "data": {
    "login": null
  }
}

Note: this is the error as observed on the wire today; extensions.code is INTERNAL_SERVER_ERROR, not a dedicated authentication code. Detect a failed login by matching the message ("Incorrect email or password"), not by branching on extensions.code.

Missing required fields in the payload: the payload must include email and password.

{
  "errors": [
    {
      "message": "Variable \"$password\" of required type \"String!\" was not provided.",
      "locations": [
        {
          "line": 1,
          "column": 33
        }
      ],
      "extensions": {
        "code": "BAD_USER_INPUT"
      }
    }
  ]
}

Refresh when the access token expires:

mutation RefreshToken($refreshToken: String) {
    refreshToken(refreshToken: $refreshToken) {
        token
        refreshToken
        expiresIn
    }
}

The refresh token rotates on every call: the response includes a new refreshToken, and you should persist that new value for the next refresh rather than reusing the one you started with. There is no session limit: logging in again for the same account (a second device, a second worker) does not invalidate an existing session's tokens.

Incorrect common error:

Invalid signature: the refresh token you provided is incorrect.

{
  "errors": [
    {
      "message": "invalid signature",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "refreshToken"
      ],
      "extensions": {
        "code": "INTERNAL_SERVER_ERROR"
      }
    }
  ],
  "data": {
    "refreshToken": null
  }
}

2.2 How long do tokens last, and do roles/scopes affect what I can do?

Access token lifetime: 15 minutes.
Refresh token: 12 hours.
Roles/permissions: determine which root operations (top-level queries and mutations) your token can reach.

Correct response to login and refreshToken mutations

{
  "data": {
    "login": {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2YWx1ZSI6IntcInVzZXJwi.....",
      "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2YWx1ZSI6IntcOjEyMDAwLFw....",
      "expiresIn": 900
    }
  }
}

What’s Next