{
  "openapi": "3.0.1",
  "info": {
    "title": "OMNO Authentication Documentation",
    "description": "## Overview\nThis API provides authentication services for OMNO.\nThe service supports OAuth2 token issuance using the client credentials flow for secure\nserver-to-server communication.\n\n## Authentication Flow\n1. Register your application to obtain client credentials (client_id and client_secret)\n2. Request an access token using the client credentials grant type\n3. Use the returned access token in the Authorization header for subsequent API calls\n\n## Obtaining Client Credentials\n\n### Production Environment\n1. Navigate to [https://cockpit.omno.com/developers/api-credentials](https://cockpit.omno.com/developers/api-credentials)\n2. Log in with your OMNO account credentials if prompted\n3. Click on \"Create Token\"\n4. Fill in the required information:\n   - Token name: Provide a descriptive name for your api token\n   - Whitelisted IPs: add you IPs or use '*' to allow all IPs\n5. Submit the form to create your credentials\n6. The system will generate and display your client_id and client_secret\n7. Store these credentials securely as the client_secret may not be displayed again\n\n## Security Best Practices\n- Store client secrets securely and never expose them in client-side code\n- Implement proper token validation on your services\n- Be aware of token expiration and implement renewal strategies\n- Use HTTPS for all communications\n\n## Support\nFor assistance with authentication issues, contact our support team at [support@omno.com](mailto:support@omno.com)\n",
    "contact": {
      "email": "support@omno.com"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://sso.omno.com",
      "description": "Production Environment\n\nThis is the main production environment for OMNO authentication services.\nAll production applications should connect to this server.\n"
    }
  ],
  "tags": [
    {
      "name": "Authentication",
      "description": "Obtain an OAuth 2.0 access token using the client credentials flow, then send it as a bearer token on every OMNO API request. Generate credentials in the dashboard under Developers → API Credentials."
    }
  ],
  "paths": {
    "/realms/{realm}/protocol/openid-connect/token": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Obtain access token using client credentials",
        "description": "## Client Credentials Flow\n\nThis endpoint implements the OAuth2 Client Credentials flow, which is designed for server-to-server\nauthentication where a client application authenticates directly to obtain an access token.\n\n### Usage Instructions\n1. Send a POST request with your client credentials in the request body\n2. Store the returned access token securely\n3. Include the access token in subsequent API requests using the Authorization header:\n   `Authorization: Bearer {access_token}`\n\n### Token Lifecycle\n- The access token is valid for the period specified in `expires_in` (typically 300 seconds)\n- After expiration, a new token must be requested\n- Implement proper error handling for token expiration scenarios\n",
        "operationId": "fetchAccessToken",
        "parameters": [
          {
            "name": "realm",
            "in": "path",
            "allowReserved": true,
            "description": "The Keycloak realm to authenticate against.\n\nThis path parameter should match the realm associated with your client credentials.\n- Use `omno` for production environment\n",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "omno"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Authentication parameters required for the client credentials flow.\n",
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "grant_type": {
                    "example": "client_credentials",
                    "type": "string",
                    "enum": [
                      "client_credentials"
                    ],
                    "description": "OAuth2 grant type identifier.\nMust be set to 'client_credentials' for this authentication flow.\n"
                  },
                  "client_id": {
                    "example": "CLIENT_ID",
                    "type": "string",
                    "description": "Your application's client identifier.\nThis ID is provided when you register your application with OMNO.\n"
                  },
                  "client_secret": {
                    "example": "CLIENT_SECRET",
                    "type": "string",
                    "description": "The secret key associated with your client_id.\nThis should be kept confidential and secure at all times.\n"
                  }
                },
                "required": [
                  "grant_type",
                  "client_id",
                  "client_secret"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful authentication response.\n\nThe response contains a JWT access token and metadata about the token,\nincluding expiration time and scope information.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenResponse"
                },
                "examples": {
                  "successResponse": {
                    "value": {
                      "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIi...",
                      "expires_in": 300,
                      "refresh_expires_in": 1800,
                      "token_type": "Bearer",
                      "scope": "profile email"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid client credentials or parameters\n\nThis error occurs when:\n- The grant_type is missing or not set to \"client_credentials\"\n- Required parameters are missing\n- Parameter format is incorrect\n"
          },
          "401": {
            "description": "Unauthorized - client authentication failed\n\nThis error occurs when:\n- The client_id doesn't exist\n- The client_secret doesn't match the registered client_id\n- The client doesn't have permission to use the client_credentials flow\n"
          }
        },
        "security": []
      }
    }
  },
  "components": {
    "schemas": {
      "TokenResponse": {
        "type": "object",
        "description": "Response object returned after successful authentication.\nContains the access token and related metadata.\n",
        "properties": {
          "access_token": {
            "type": "string",
            "example": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIi...",
            "description": "JWT access token used for authentication.\n\nThis token should be included in the Authorization header of subsequent API requests:\n`Authorization: Bearer {access_token}`\n\nThe token contains encoded claims about the authenticated client and its permissions.\n"
          },
          "expires_in": {
            "type": "integer",
            "example": 300,
            "description": "Token expiration time in seconds.\n\nThis value indicates how long the access_token will remain valid.\nTypically set to 300 seconds (5 minutes) in OMNO environments.\n"
          },
          "refresh_expires_in": {
            "example": 1800,
            "type": "integer",
            "description": "Refresh token expiration time in seconds.\n\nNote: While this field is included in the response, refresh tokens are not\ntypically used with the client credentials flow as new access tokens\ncan be obtained directly using the client credentials.\n"
          },
          "token_type": {
            "example": "Bearer",
            "type": "string",
            "description": "Type of token issued.\n\nAlways set to \"Bearer\" for OMNO authentication, indicating the token\nshould be used in the Authorization header as a bearer token.\n"
          },
          "scope": {
            "example": "profile email",
            "type": "string",
            "description": "Space-delimited list of scopes granted to the token.\n\nThese scopes define the permissions associated with the token.\nCommon scopes include \"profile\" and \"email\".\n"
          }
        }
      }
    }
  }
}