GraphQL User & Authentication

PagibleAI uses your Laravel application’s default authentication guard. The GraphQL login mutation starts a session for an existing user; CMS permissions decide which queries and mutations that user may run.

Start with the PagibleAI GraphQL API guide for the request headers, JSON scalar rule and complete curl setup. This page focuses on the authentication lifecycle and CMS-specific user fields.

Grant editor access

Create the user through your application, then grant CMS editor permissions from the project directory:

php artisan cms:editor editor@example.com

Remove the editor role when the account should no longer access the CMS:

php artisan cms:editor --disable editor@example.com

Log in

cmsLogin accepts the user’s email address and password and returns the application’s User type. In a browser client, retain the session cookie by sending requests with credentials: "include".

mutation Login($email: String!, $password: String!) {
  cmsLogin(email: $email, password: $password) {
    id
    name
    email
  }
}
{
  "email": "editor@example.com",
  "password": "secret"
}

Repeated failed logins are rate-limited. Treat credentials as secrets and use HTTPS outside local development.

Login error response

{
  "errors": [
    {
      "message": "Invalid credentials",
      "path": ["cmsLogin"]
    }
  ],
  "data": null
}

Three failed attempts for the same email address and IP trigger a 60-second rate limit. Do not distinguish unknown users from incorrect passwords in your client messages.

Read the current CMS user

Use me after authentication. Unlike the application’s normal User type, CmsUser includes resolved CMS permissions, named roles and editor preferences.

query CurrentCmsUser {
  me {
    id
    name
    email
    permission
    roles
    settings
  }
}
{
  "data": {
    "me": {
      "id": "42",
      "name": "CMS editor",
      "email": "editor@example.com",
      "permission": "{\"page:view\":true,\"page:add\":true,\"page:save\":true}",
      "roles": [
        "editor"
      ],
      "settings": "{\"lang\":\"en\",\"theme\":\"dark\"}"
    }
  }
}

After the mutation succeeds, run CurrentCmsUser again and parse me.settings to confirm the stored preferences. cmsUser deliberately returns the application User, so selecting settings, roles or permission directly from its result is invalid.

CmsUser fields

Field
Type
Meaning
id
ID!
Application user identifier
name
String!
Display name
email
String!
Email address
permission
JSON!
JSON-encoded resolved capabilities keyed by action
roles
[String!]!
Named CMS roles assigned to the user
settings
JSON
JSON-encoded editor preferences, or null

Update editor preferences

cmsUser stores the JSON document you provide in the authenticated user’s CMS settings. Because the MLL JSON scalar expects a JSON-encoded string, stringify the settings object once in your variables. The mutation returns the application User, so query me afterwards when you want to read the CMS-specific settings field.

mutation SavePreferences($settings: JSON!) {
  cmsUser(settings: $settings) {
    id
    name
    email
  }
}
{
  "settings": "{\"lang\":\"de\",\"theme\":\"dark\",\"page\":{\"filter\":{\"view\":\"list\"}}}"
}

After the mutation succeeds, run CurrentCmsUser again and parse me.settings to confirm the stored preferences. cmsUser deliberately returns the application User, so selecting settings, roles or permission directly from its result is invalid.

The decoded settings document is limited to 64 KB. permission and settings are returned as JSON-encoded strings, so parse them before use. Do not store credentials or access tokens in this field.

Log out

cmsLogout ends the authenticated session, invalidates its session data and rotates the CSRF token.

After logout, discard cached user data and obtain a fresh session and CSRF token before the next login attempt.

mutation Logout {
  cmsLogout {
    id
    name
    email
  }
}

Permission errors

Authentication only identifies the user. Each protected field also checks the relevant CMS capability, such as page:view or file:save. A logged-in user without that capability receives a GraphQL error. Check the top-level errors array and do not assume login grants full CMS access.

{
  "errors": [
    {
      "message": "Insufficient permissions",
      "path": ["pages"]
    }
  ],
  "data": {
    "pages": null
  }
}

Authentication troubleshooting

Common authentication problems

Symptom
Cause
Resolution
HTTP 419
Missing or stale CSRF token
Refresh the session and resend the decoded XSRF cookie as a header
Invalid credentials
Email or password was rejected
Check the account without exposing which credential failed
Too many login attempts
Three failures triggered throttling
Wait at least 60 seconds before retrying
Unauthenticated
The session cookie is absent or expired
Send credentials with the request and log in again
Insufficient permissions
The user is authenticated but lacks a CMS capability
Inspect parsed me.permission and update the assigned role
Cannot query field on User
A CMS-only field was selected from cmsUser or cmsLogin
Request permission, roles and settings through me