> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sagescreen.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Obtain a JWT token pair

> Authenticates a user with username + password and returns a signed
JWT auth token plus a refresh token. All existing tokens for the
user are cleaned up before issuing new ones.

**Public endpoint** — no prior auth required.




## OpenAPI

````yaml /openapi/private/specs/wp/auth.yml post /auth/token
openapi: 3.1.0
info:
  title: SageScreen — Auth Module
  description: >
    Authentication and session management. Handles JWT token lifecycle

    (issue, refresh, validate, revoke) and WordPress-based login/logout

    with reCAPTCHA/Turnstile protection.


    Uses RS256-signed JWTs stored in the `wp_sage_screen_jwt` table.

    Tokens have a configurable TTL (`sage_screen_jwt_expires`, default 3600 s)

    and a separate refresh window (`sage_screen_jwt_refresh_expires`, default
    604800 s / 7 days).
  version: 1.0.0
servers:
  - url: https://{domain}/wp-json/sagescreen/v1
    description: WordPress REST API
    variables:
      domain:
        default: api.sagescreen.app
security: []
tags:
  - name: Auth – REST
    description: JWT token endpoints (REST API)
  - name: Auth – AJAX
    description: Session-based login / logout / password flows (AJAX)
paths:
  /auth/token:
    post:
      tags:
        - Auth – REST
      summary: Obtain a JWT token pair
      description: |
        Authenticates a user with username + password and returns a signed
        JWT auth token plus a refresh token. All existing tokens for the
        user are cleaned up before issuing new ones.

        **Public endpoint** — no prior auth required.
      operationId: authGetToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetTokenRequest'
            example:
              username: john.doe
              password: SecurePass123
      responses:
        '200':
          description: Token pair issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenPairResponse'
              example:
                token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
                refresh_token: dGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIHRva2Vu...
        '400':
          description: Missing credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WPError'
              example:
                code: missing_credentials
                message: Username and password are required
                data:
                  status: 400
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WPError'
              example:
                code: authentication_failed
                message: Invalid credentials
                data:
                  status: 401
        '500':
          description: Token generation failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WPError'
              example:
                code: token_generation_failed
                message: Failed to generate tokens
                data:
                  status: 500
      security: []
components:
  schemas:
    GetTokenRequest:
      type: object
      required:
        - username
        - password
      properties:
        username:
          type: string
          examples:
            - john.doe
        password:
          type: string
          format: password
          examples:
            - SecurePass123
    TokenPairResponse:
      type: object
      required:
        - token
        - refresh_token
      properties:
        token:
          type: string
          description: RS256-signed JWT (see JWTPayload for decoded structure)
          examples:
            - eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
        refresh_token:
          type: string
          description: Base64-encoded 64-byte random refresh token
          examples:
            - dGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIHRva2Vu...
    WPError:
      type: object
      description: Standard WordPress REST API error envelope
      required:
        - code
        - message
        - data
      properties:
        code:
          type: string
          description: Machine-readable error code
          examples:
            - missing_credentials
        message:
          type: string
          description: Human-readable error message
          examples:
            - Username and password are required
        data:
          type: object
          required:
            - status
          properties:
            status:
              type: integer
              description: HTTP status code
              examples:
                - 400

````