{
  "openapi": "3.0.1",
  "info": {
    "title": "Clerk Tools User Authorization",
    "version": "v0",
    "description": "This service provides endpoints for obtaining and refreshing OAuth2-style tokens.\n\n### Typical Usage Flow (Web or Mobile Application)\n1. Call **`/api/auth/token`** with **Basic Authentication** (username/password) to generate an **access_token** and a **refresh_token**.\n2. Use the **access_token** (JWT) in requests to access secure APIs:\n   ```\n   Authorization: Bearer {access_token}\n   ```\n3. When the access token expires, you can either:\n   - Generate a new token again with **username/password** using `/api/auth/token`, OR\n   - Continue the session without username/password by using the **refresh_token** at `/api/auth/refresh`.\n\n### Machine-to-Machine (M2M) Authentication\n- Call **`/api/auth/token`** with **Basic Authentication** using client credentials (client_id/client_secret).\n- Only an **access_token** is returned; no **refresh_token** is issued for M2M.\n- When the access token expires, the client must request a new token using its credentials.\n\n### Refresh Behavior (Web/Mobile Only)\n- A new access token is generated.\n- Both a new access token and a new refresh token are returned.\n- The previous **refresh_token** expires.\n\n⚠️ **Important:** Store the `refresh_token` securely on the client (e.g., secure storage in mobile apps). Do not expose or transmit the `refresh_token` outside the application."
  }
  ,
  "servers": [
    {
      "url": "https://testauthgateway.flclerktools.com",
      "description": "Clerk Tools Test Authentication Server"
    }
  ],
  "tags": [
    {
      "name": "Authentication Service",
      "description": "Endpoints for generating and refreshing access tokens."
    }
  ],
  "paths": {
    "/api/auth/token": {
      "post": {
        "tags": ["Authentication Service"],
        "summary": "Generate Token",
        "operationId": "createToken",
        "description": "Authenticate using **Basic Authentication** with username/password or client credentials.\n\nThis endpoint is typically used by a web or mobile application at login when the user first enters their credentials.\n\nReturns an **access_token** and, optionally, a **refresh_token** depending on the type of authentication.\n\n**Note: The refresh_token is only issued for web or mobile authentication users; it is not returned for machine-to-machine (M2M) authentication**.\n\n**Header example**:\n```\nAuthorization: Basic base64(username:password)\n```",
        "security": [
          { "basicAuth": [] }
        ],
        "responses": {
          "200": {
            "description": "Token generated successfully",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/OAuth2TokenResponse" },
                "example": {
                  "access_token": "eyJhbGciOiJFUzI1NiJ9...",
                  "token_type": "Bearer",
                  "expires_in": 300,
                  "refresh_token": "95CCF8D8-C4D1-4471-8DE5-4B695C065163"
                }
              }
            }
          },
          "401": {
            "description": "Invalid username or password",
            "content": {
              "text/plain": {
                "schema": { "type": "string" },
                "example": "Invalid username or password"
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "text/plain": {
                "schema": { "type": "string" },
                "example": "Server Exception: ..."
              }
            }
          }
        }
      }
    },
    "/api/auth/refresh": {
      "post": {
        "tags": ["Authentication Service"],
        "summary": "Refresh Token",
        "operationId": "refreshToken",
        "description": "Use the **refresh_token** to continue a user session without requiring the user to re-enter authentication details.\n\nThis endpoint is typically used by web or mobile applications after login to keep the user signed in.\n\n**Header example**:\n```\nAuthorization: Bearer {refresh_token}\n```\n\n**Refresh behavior:**\n- A new access token is generated.\n- Both a new access token and a new refresh token are returned.\n- The previous **refresh_token** expires.\n\n⚠️ **Important:** Never expose the `refresh_token` outside of the application. It must be stored securely and treated as highly sensitive.",
        "security": [
          { "bearerAuth": [] }
        ],
        "responses": {
          "200": {
            "description": "Token refreshed successfully",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/OAuth2TokenResponse" },
                "example": {
                  "access_token": "eyJhbGciOiJFUzI1NiJ9...",
                  "token_type": "Bearer",
                  "expires_in": 300,
                  "refresh_token": "AA11BB22-CC33-DD44-EE55-FF6677889900"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or expired refresh token",
            "content": {
              "text/plain": {
                "schema": { "type": "string" },
                "example": "Invalid or expired refresh token"
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "text/plain": {
                "schema": { "type": "string" },
                "example": "Server Exception: ..."
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "OAuth2TokenResponse": {
        "type": "object",
        "description": "Response returned after successful authentication/refresh.",
        "properties": {
          "access_token": {
            "type": "string",
            "description": "JWT access token used to access secure Clerk Tools APIs.",
            "example": "eyJhbGciOiJFUzI1NiJ9..."
          },
          "token_type": {
            "type": "string",
            "description": "Token type; typically 'Bearer'.",
            "example": "Bearer"
          },
          "expires_in": {
            "type": "integer",
            "format": "int64",
            "description": "Number of seconds until the access token expires.",
            "example": 300
          },
          "refresh_token": {
            "type": "string",
            "description": "Refresh token used to obtain a new access token. Previous refresh_token expires when a new one is issued. Must be stored securely and never exposed outside the application. Not generated for machine-to-machine (M2M) authentication; only available for web or mobile login.",
            "example": "95CCF8D8-C4D1-4471-8DE5-4B695C065163"
          }
        },
        "required": ["access_token", "token_type", "expires_in", "refresh_token"]
      }
    },
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic",
        "description": "Basic Authentication using username and password."
      },
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Use the **refresh_token** as the Bearer credential on `/api/auth/refresh`. Must be kept secure and not exposed outside the application."
      }
    }
  }
}