Authentication - Kralis Docs

Kralis uses one SimpleJWT token family across its GraphQL and REST authentication interfaces. GraphQL is the recommended lifecycle and is also used by Kralis Web.

Client choice	Authenticate through	Product GraphQL route	Refresh through
GraphQL	`login` mutation	`/graphql/` or `/graphiql/`	`refreshLoginToken` mutation
REST compatibility	`POST /auth/login/`	`/graphql/` or `/graphiql/`	`POST /auth/token/refresh/`

The two login interfaces apply the same account, school, and Access-PIN rules and issue compatible access and refresh tokens. Choose one lifecycle and use it consistently in your client.

GraphQL authentication lifecycle

mutation Login($input: LoginInput!) {
  login(input: $input) {
    access
    refresh
    user {
      id
      pk
      username
      fullName
      role
    }
    school {
      id
      pk
      schoolName
      schoolAcronym
      isActive
    }
  }
}

After login, send the access token and query the trusted context for the current request:

query Viewer {
  viewer {
    user {
      id
      pk
      username
      fullName
      role
    }
    school {
      id
      pk
      schoolName
      schoolAcronym
    }
    accessContext {
      yearId
      termId
      classeId
      remainingPinUsage
      usesAccessPin
    }
  }
}

{
  "input": {
    "username": "YOUR_USERNAME",
    "password": "YOUR_PASSWORD_OR_ACCESS_PIN"
  }
}

REST compatibility lifecycle

Endpoint	Purpose
`POST /auth/login/`	Exchange username and password or Access PIN for tokens
`GET /auth/user/`	Read current authenticated user details
`POST /auth/token/refresh/`	Refresh a valid token and return the current token pair
`POST /auth/token/verify/`	Verify an access or refresh token
`POST /auth/token/revoke/`	Revoke the submitted refresh token and end that device session
`POST /auth/token/revoke-all/`	Invalidate the signed-in user’s tokens on all devices

Confirm current REST fields in Swagger or ReDoc.

Authorize GraphQL calls

Authorization: Bearer YOUR_ACCESS_TOKEN

The login response includes deliberately limited user and school identity data. Fetch the live academic and Access-PIN context through viewer.accessContext, and fuller application data through the appropriate school-scoped GraphQL queries.

Refresh and revocation

mutation Refresh($input: RefreshLoginTokenInput!) {
  refreshLoginToken(input: $input) {
    access
    refresh
  }
}

mutation Verify($input: VerifyLoginTokenInput!) {
  verifyLoginToken(input: $input) {
    valid
  }
}

mutation Revoke($input: RevokeLoginTokenInput!) {
  revokeLoginToken(input: $input) {
    revoked
  }
}

Mutation	Input
`refreshLoginToken`	`{ "refresh": "YOUR_REFRESH_TOKEN" }`
`verifyLoginToken`	`{ "token": "YOUR_ACCESS_OR_REFRESH_TOKEN" }`
`revokeLoginToken`	`{ "refresh": "YOUR_REFRESH_TOKEN" }`

After every successful refresh, replace both stored tokens with the returned access and refresh, even when the refresh value is unchanged by the current server policy. This keeps a client correct if token rotation is enabled later. If refresh fails with INVALID_TOKEN, clear local authentication and require sign-in. Coalesce concurrent refresh attempts so the same token is not submitted several times, and do not create an infinite retry loop.

Storage guidance

Client	Preferred approach
Server-rendered web app	Keep tokens server-side and expose an HttpOnly, Secure session cookie to the browser
Browser-only app	Minimize token exposure; do not place credentials in source, URLs, or analytics
Mobile app	Use the operating system’s secure credential storage
Development tool	Use temporary environment configuration excluded from version control

Never return tokens to logs, error trackers, browser URLs, screenshots, or public support messages.

​GraphQL authentication lifecycle

​REST compatibility lifecycle

​Authorize GraphQL calls

​Refresh and revocation

​Storage guidance

GraphQL authentication lifecycle

REST compatibility lifecycle

Authorize GraphQL calls

Refresh and revocation

Storage guidance