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

> ## Agent Instructions
> OwnPay is licensed under AGPL-3.0 and is completely free - no licensing fees.
> Production docs URL: https://ownpay.org/docs - append .md to any page URL for clean markdown.
> OwnPay requires PHP 8.3+, MySQL/MariaDB, and Redis.
> MCP server available at https://ownpay.org/docs/mcp for programmatic documentation queries.
> Use root-relative links (e.g. /quickstart) for internal navigation - do NOT include /docs prefix.
> Plugin development: consult /developer/plugin-types/ pages for correct interfaces and manifests.

# Refresh Access Token

> Refreshes a short-lived access JWT (valid for 24h) using a long-lived refresh JWT (issued with a 30-day TTL).
Performs fingerprint checking for device identification validation.




## OpenAPI

````yaml /api/mobile_api.yaml post /api/mobile/v1/devices/token-refreshes
openapi: 3.1.0
info:
  title: OwnPay Mobile Companion App API
  description: >
    The OwnPay Mobile API is exposed exclusively to the paired mobile companion
    application.

    It contains endpoints to complete initial device pairing, submit heartbeats
    to report online statuses, refresh authentication tokens, upload received
    SMS messages (supporting batch processing up to 200 items), fetch pending
    outbound SMS queues, acknowledge push notifications, and retrieve dashboard
    statistics.


    ### Security and Cryptography

    - Except for `/api/mobile/v1/devices` (bootstrap pairing) and
    `/api/mobile/v1/devices/token-refreshes` (token refresh), all endpoints
    require authentication using a JSON Web Token (JWT) in the HTTP
    `Authorization` header.
      ```http
      Authorization: Bearer <jwt_access_token>
      ```
    - Device fingerprints are checked during token refreshes.

    - Endpoints are brand-scoped; data visibility is restricted to the specific
    brand/merchant.
  version: 1.0.0
servers:
  - url: https://{brand_domain}
    description: Master brand domain hosting OwnPay gateway.
    variables:
      brand_domain:
        default: ownpay.org
        description: The domain of the specific white-labeled gateway.
security:
  - JWTAuth: []
paths:
  /api/mobile/v1/devices/token-refreshes:
    post:
      summary: Refresh Access Token
      description: >
        Refreshes a short-lived access JWT (valid for 24h) using a long-lived
        refresh JWT (issued with a 30-day TTL).

        Performs fingerprint checking for device identification validation.
      operationId: refreshToken
      parameters:
        - name: X-Device-Fingerprint
          in: header
          required: false
          description: >-
            Unique device hardware fingerprint hash. Required if not passed in
            the request body.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshTokenRequest'
      responses:
        '200':
          description: Tokens refreshed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefreshTokenResponse'
        '401':
          description: >-
            Authentication failed. The device may have been revoked, or the
            fingerprint does not match.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSingleErrorResponse'
        '422':
          description: Validation error (e.g. missing refresh_token or fingerprint).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSingleErrorResponse'
      security: []
components:
  schemas:
    RefreshTokenRequest:
      type: object
      required:
        - refresh_token
      properties:
        refresh_token:
          type: string
          description: Long-lived refresh JWT.
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.refresh...
        fingerprint:
          type: string
          description: >-
            Hardware fingerprint signature. Required if the
            `X-Device-Fingerprint` header is missing.
          example: a6829d10e83b1
    RefreshTokenResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            access_token:
              type: string
              description: Fresh access JWT.
              example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.newaccess...
            refresh_token:
              type: string
              description: Fresh refresh JWT.
              example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.newrefresh...
            expires_in:
              type: integer
              example: 86400
            server_time:
              type: string
              format: date-time
              example: '2026-06-23T14:25:00Z'
    ApiSingleErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: Invalid pairing code
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                example: INVALID_PAIRING_CODE
              message:
                type: string
                example: Invalid pairing code
              field:
                type: string
                nullable: true
                example: null
        request_id:
          type: string
          example: 8f5a2e9b0c7d4e5f
  securitySchemes:
    JWTAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Enter your Short-lived access JWT token.

````

## Related topics

- [Pair Mobile Companion Device](/docs/api-reference/pair-mobile-companion-device.md)
- [Features and Capabilities](/docs/resources/features.md)
- [Mobile API Reference - Companion App and SMS Forwarding](/docs/api-reference/mobile.md)
- [API Authentication - Bearer Tokens and API Key Scoping](/docs/api/authentication.md)
- [Merchant API Reference - Payments, Refunds, and Webhooks](/docs/api-reference/merchant.md)