{
  "openapi": "3.0.3",
  "info": {
    "title": "Fibre Gateway : Authentication",
    "version": "1.0",
    "description": "# Introduction\n\nThe Fibre Cafe is a scalable, unified platform to support L2C provisioning, in-life modification/cease and\nT2R trouble resolution between communication providers (CP) and network operators or aggregators.\n\nThe Fibre Cafe is secured using the standard OAuth 2.0 authorization protocol - all requests must include a valid\naccess token. Tenant access tokens provide access to the Tenant API and supplier access tokens provide access to\nthe Supplier Updates API. IP address whitelisting is also enabled so all callers must provide the static public IP\naddress for any inbound traffic.\n\nAccess tokens can be retrieved from this endpoint - they are intended to be re-used and not created per request. \nThe tokens will expire in 60 minutes by default - at which point a new token can be requested.\n__\n\n© 2022-2026 Strategic Imperatives\n"
  },
  "servers": [
    {
      "url": "https://dev.fibregateway.com/v1"
    }
  ],
  "paths": {
    "/auth/tenant/access-token": {
      "post": {
        "summary": "Tenant authentication - retrieve access token.",
        "description": "This endpoint is called to retrieve an access token which must be provided in the header\non subsequent tenant calls to the gateway.\n\nEither Authorization header or client id/secret must be provided.\n",
        "operationId": "getTenantAccessToken",
        "security": [
          {}
        ],
        "parameters": [
          {
            "name": "Authorization",
            "description": "The Authorization header is Basic Base64-encoded app client credentials - client_id:client_secret",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "grant_type"
                ],
                "properties": {
                  "grant_type": {
                    "description": "Grant type - only client_credentials is supported at the moment",
                    "type": "string",
                    "example": "client_credentials"
                  },
                  "scope": {
                    "description": "Limit to space-delimited list of scopes registered with the app client (optional)",
                    "type": "string",
                    "example": "com.fibregateway.<ENV_NAME>/tenant.all.all"
                  },
                  "client_id": {
                    "description": "The ID of the app client - required if not using Authorization header",
                    "type": "string"
                  },
                  "client_secret": {
                    "description": "The client secret for the app client - required if not using Authorization header",
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully generated access token",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Represents authentication response including access token.",
                  "type": "object",
                  "properties": {
                    "access_token": {
                      "description": "Access token to use in requests",
                      "type": "string",
                      "example": "eyJraWQiOiI3WEl6amJaakZjYlpWK..."
                    },
                    "expires_in": {
                      "description": "Token expiry in seconds (TTL)",
                      "type": "string",
                      "example": 3600
                    },
                    "token_type": {
                      "description": "Token type",
                      "type": "string",
                      "example": "Bearer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - authentication failed",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Supplied request was malformed or missing mandatory parameters",
                  "type": "object",
                  "properties": {
                    "error": {
                      "description": "Reason for failure:\n- invalid_request - request is missing a required parameter or is otherwise malformed\n- invalid_client - client authentication failed - no such client id and/or secret\n- invalid_grant - access issue or access has been revoked\n- unauthorized_client - client is not authorized \n- unsupported_grant_type - an unrecognised grant type was specified\n",
                      "type": "string",
                      "example": "invalid_request|invalid_client|invalid_grant|unauthorized_client|unsupported_grant_type"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Fibre Gateway is temporarily unavailable"
          }
        }
      }
    },
    "/auth/supplier/access-token": {
      "post": {
        "summary": "Supplier KCI authentication - retrieve access token.",
        "description": "This endpoint is called to retrieve an access token which must be provided in the header\non subsequent supplier KCI calls to the gateway.\n\nEither Authorization header or client id/secret must be provided.\n",
        "operationId": "getSupplierAccessToken",
        "security": [
          {}
        ],
        "parameters": [
          {
            "name": "Authorization",
            "description": "The Authorization header is Basic Base64-encoded app client credentials - client_id:client_secret",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "grant_type"
                ],
                "properties": {
                  "grant_type": {
                    "description": "Grant type - only client_credentials is supported at the moment",
                    "type": "string",
                    "example": "client_credentials"
                  },
                  "scope": {
                    "description": "Limit to space-delimited list of scopes registered with the app client (optional)",
                    "type": "string",
                    "example": "com.fibregateway.<ENV_NAME>/tenant.all.all"
                  },
                  "client_id": {
                    "description": "The ID of the app client - required if not using Authorization header",
                    "type": "string"
                  },
                  "client_secret": {
                    "description": "The client secret for the app client - required if not using Authorization header",
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully generated access token",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Represents authentication response including access token.",
                  "type": "object",
                  "properties": {
                    "access_token": {
                      "description": "Access token to use in requests",
                      "type": "string",
                      "example": "eyJraWQiOiI3WEl6amJaakZjYlpWK..."
                    },
                    "expires_in": {
                      "description": "Token expiry in seconds (TTL)",
                      "type": "string",
                      "example": 3600
                    },
                    "token_type": {
                      "description": "Token type",
                      "type": "string",
                      "example": "Bearer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - authentication failed",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Supplied request was malformed or missing mandatory parameters",
                  "type": "object",
                  "properties": {
                    "error": {
                      "description": "Reason for failure:\n- invalid_request - request is missing a required parameter or is otherwise malformed\n- invalid_client - client authentication failed - no such client id and/or secret\n- invalid_grant - access issue or access has been revoked\n- unauthorized_client - client is not authorized \n- unsupported_grant_type - an unrecognised grant type was specified\n",
                      "type": "string",
                      "example": "invalid_request|invalid_client|invalid_grant|unauthorized_client|unsupported_grant_type"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Fibre Gateway is temporarily unavailable"
          }
        }
      }
    }
  },
  "components": {}
}