{
  "openapi": "3.1.0",
  "info": {
    "title": "Auth API",
    "version": "v3.2.1.1",
    "contact": {
      "name": "API Support Group",
      "email": "api@yellowdogsoftware.com"
    },
    "description": "# \n![REST API logo](../../resources/rest-api-cloud-logo.png)\n\n<hr/>\n",
    "license": {
      "name": "proprietary"
    }
  },
  "servers": [
    {
      "url": "https://auth.yellowdogsoftware.com",
      "description": "Production server"
    }
  ],
  "paths": {
    "/token": {
      "post": {
        "operationId": "get-token",
        "tags": [
          "Authentication Tokens"
        ],
        "summary": "Get token via credential",
        "description": "",
        "requestBody": {
          "description": "",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Json.Credential"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Json.GeneratedTokenResponse"
                }
              }
            }
          },
          "500": {
            "description": "An internal error has occured or the database is currently offline for connections.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Json.ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/refreshToken": {
      "post": {
        "operationId": "get-refreshtoken",
        "tags": [
          "Authentication Tokens"
        ],
        "summary": "Get token via refresh token",
        "description": "",
        "requestBody": {
          "description": "",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Json.RefreshToken"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Json.GeneratedTokenResponse"
                }
              }
            }
          },
          "500": {
            "description": "An internal error has occured or the database is currently offline for connections.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Json.ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Json.Credential": {
        "type": "object",
        "properties": {
          "clientId": {
            "description": "This is an alphanumeric identifier of a specific Yellow Dog database.",
            "type": [
              "string"
            ],
            "example": "ABC123"
          },
          "userName": {
            "description": "This name identifies a user registered with the database represented by the clientId. If this user has API access privileges, they will be able to request an access token.\n",
            "type": [
              "string"
            ],
            "example": "bi_dashboard_api_key"
          },
          "password": {
            "description": "This password completes a credential for a given user within a specific database.",
            "type": [
              "string"
            ],
            "example": "xyz-123-abc-789-pqr"
          }
        },
        "additionalProperties": false
      },
      "Json.RefreshToken": {
        "type": "object",
        "properties": {
          "clientId": {
            "description": "This is an alphanumeric identifier of a specific Yellow Dog database.",
            "type": [
              "string"
            ],
            "example": "ABC123"
          },
          "refreshToken": {
            "description": "A UUID representing a refresh token.",
            "type": [
              "string"
            ],
            "example": "01234567-0123-abcd-0123-abcdef012345"
          }
        },
        "additionalProperties": false
      },
      "Json.GeneratedTokenResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": [
              "string"
            ],
            "example": true
          },
          "result": {
            "type": "object",
            "properties": {
              "accessToken": {
                "description": "A JWT access token.",
                "type": [
                  "string"
                ],
                "example": "xxxxx.yyyyy.zzzzz"
              },
              "refreshToken": {
                "description": "A UUID representing a refresh token.",
                "type": [
                  "string"
                ],
                "example": "01234567-0123-abcd-0123-abcdef012345"
              },
              "tokenType": {
                "type": [
                  "string"
                ],
                "example": "bearer"
              },
              "clientId": {
                "description": "This is an internal numeric key corresponding to the alphanumeric clientId provided as input.",
                "type": "integer",
                "format": "int32",
                "example": 3210
              },
              "databaseVersion": {
                "description": "This is the detected version for the database described by the input clientId.",
                "type": "integer",
                "format": "int32",
                "example": 377
              },
              "expiresIn": {
                "description": "Seconds remaining until the accessToken expires.",
                "type": "integer",
                "format": "int32",
                "example": 3600
              },
              "expires": {
                "description": "Timestamp indicating when the accessToken will expire.",
                "type": [
                  "string"
                ],
                "format": "date-time",
                "example": "2025-10-20T14:45:06Z"
              },
              "isUser": {
                "description": "Indicates whether there is user associated with this type of access token.",
                "type": "boolean",
                "example": true
              },
              "authType": {
                "type": "integer",
                "description": "Allows alternative authentication types to be distinguished if added in the future.",
                "format": "int32",
                "example": 1
              }
            }
          },
          "errors": {
            "type": [
              "string",
              "null"
            ],
            "example": null
          }
        },
        "additionalProperties": false
      },
      "Json.ErrorMessage": {
        "type": "object",
        "properties": {
          "message": {
            "type": [
              "string",
              "null"
            ]
          },
          "extensions": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": false
      },
      "Json.ErrorResponse": {
        "type": "object",
        "properties": {
          "message": {
            "type": [
              "string",
              "null"
            ]
          },
          "errors": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/Json.ErrorMessage"
            }
          }
        },
        "additionalProperties": false
      }
    }
  },
  "tags": [
    {
      "name": "Authentication Tokens",
      "description": "The Yellow Dog Auth API allows developers to generate \n[JWT](https://jwt.io/) authentication tokens\nfor access to protected services such as\n[the Fetch API](../fetch/api)\nand other future services.\n\n\n**Two Kinds of Tokens**\n\nThere are two kinds of token issued by this Auth API:\n1. __Access Token__ -- A short lived [JWT](https://jwt.io/) bearer token that provides \\\naccess to services such as [Fetch API](../fetch/api) endpoints. \\\nThe lifespan of these \\tokens is measured in minutes, typically 60 minutes.\n1. __Refresh Token__ -- A longer lived, single use, [UUID/GUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) that can be\nexchanged for a fresh new pair of Access and Refresh Tokens. The lifespan of\na Refresh Token is measured in days, typically 30 days.\n\n\n**Token Generation Input Credendials**\n\nIf you have a valid Refresh Token, you can use it with the\n[POST /refreshtoken](./api/authentication-tokens/get-refreshtoken)\nendpoint to obtain a new pair of Access and Refresh Tokens.\n\nIf you don't have a valid Access or Refresh Token, you can obtain both by submitting\nprimary credentials consisting of a username, password, and client ID to the\n[POST /token](./api/authentication-tokens/get-token)\nendpoint of the Auth API.\nOnce you have a valid Refresh Token, you can use it on a system that is exposed to\nexternal traffic without having to store your primary credentials there.\nSince a Refresh Token can only be used once before it expires, an unexpectedly invalid\nRefresh Token indicates that the exposed system was likely compromised.\nYou can recover by generating new tokens from your primary credentials in a protected\nenvironment while separately escalating the security breach.\n"
    }
  ]
}