{
  "openapi": "3.0.3",
  "info": {
    "version": "1.0.0",
    "title": "Authentication",
    "description": "This is OpenAPI Spec APIs for external partners to authenticate and verify customers securely.",
    "contact": {
      "name": "Omni API Support",
      "email": "DL-OmniAdapter@att.com"
    }
  },
  "servers": [
    {
      "url": "https://partner-omni-apis-omni-apis.att.com/omni-svcs"
    }
  ],
  "tags": [
    {
      "name": "customer-management",
      "description": "Customer Management"
    }
  ],
  "paths": {
    "/v1/identity/auth-methods": {
      "post": {
        "tags": [
          "customer-management"
        ],
        "description": "Returns a list of supported authentication methods (e.g., OTP, passcode) for a customer based on the provided intent and Customer details",
        "summary": "Authentication methods",
        "operationId": "getAuthMethods",
        "requestBody": {
          "description": "Auth methods request body",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "intent": {
                    "type": "string",
                    "description": "intent of the order transaction ex: upgrade, add aline, swap"
                  },
                  "firstName": {
                    "type": "string",
                    "description": "firstname of the user authenticating for order transaction"
                  },
                  "lastName": {
                    "type": "string",
                    "description": "firstname of the user authenticating for order transaction"
                  },
                  "subscriberNumber": {
                    "type": "string"
                  },
                  "emailAddress": {
                    "type": "string"
                  }
                },
                "required": [
                  "intent",
                  "firstName",
                  "lastName",
                  "subscriberNumber"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/AuthMethodsResponse"
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "errorCode": "400-INVALID-REQUEST",
                    "errorDescription": "Validation Failure",
                    "errorList": [
                      {
                        "action": "auth",
                        "errorCode": "AUTH-142",
                        "errorDescription": "",
                        "errorDetails": [
                          {
                            "system": "IDGRAPH",
                            "errorCode": "IDG-1235",
                            "errorDescription": ""
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/customer/auth": {
      "post": {
        "tags": [
          "customer-management"
        ],
        "description": "Validates customer credentials and returns the authentication status along with detailed error information if applicable.",
        "summary": "Customer Authentication",
        "operationId": "authenticateCustomer",
        "requestBody": {
          "description": "Auth request body",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "subscriberNumber": {
                    "type": "string"
                  },
                  "otp": {
                    "type": "object",
                    "properties": {
                      "pin": {
                        "type": "string",
                        "description": "pin value for authentication"
                      },
                      "deliveryMethod": {
                        "type": "string",
                        "description": "List of delivery channels (e.g., email, phone number) through which the OTP for PIN request can be sent"
                      }
                    }
                  },
                  "passcode": {
                    "type": "string"
                  }
                },
                "required": [
                  "subscriberNumber"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/AuthSuccessResponse"
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "errorCode": "400-INVALID-REQUEST",
                    "errorDescription": "Validation Failure",
                    "errorList": [
                      {
                        "action": "auth",
                        "errorCode": "AUTH-142",
                        "errorDescription": "",
                        "errorDetails": [
                          {
                            "system": "IDGRAPH",
                            "errorCode": "IDG-1235",
                            "errorDescription": ""
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/otp/send": {
      "post": {
        "tags": [
          "customer-management"
        ],
        "description": "Initiates OTP generation and delivery to the customer via specified channels such as email or mobile number.",
        "summary": "Generate OTP",
        "operationId": "generateOtp",
        "requestBody": {
          "description": "Generate OTP request body",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "subscriberNumber": {
                    "type": "string"
                  },
                  "deliveryMethods": {
                    "type": "array",
                    "description": "List of delivery channels (e.g., email, phone number) through which the OTP for PIN request can be sent",
                    "items": {
                      "type": "object",
                      "properties": {
                        "key": {
                          "type": "string",
                          "description": "Type of delivery method, such as 'email' or 'ctn' (cellular telephone number)"
                        },
                        "value": {
                          "type": "string",
                          "description": "The actual destination value for the delivery method, such as an email address or phone number"
                        }
                      }
                    }
                  }
                },
                "required": [
                  "subscriberNumber",
                  "deliveryMethods"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/GenerateOtpResponse"
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "errorCode": "400-INVALID-REQUEST",
                    "errorDescription": "Validation Failure",
                    "errorList": [
                      {
                        "action": "auth",
                        "errorCode": "AUTH-142",
                        "errorDescription": "",
                        "errorDetails": [
                          {
                            "system": "IDGRAPH",
                            "errorCode": "IDG-1235",
                            "errorDescription": ""
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "errorCode": {
            "type": "string",
            "description": "error code",
            "example": "<400-INVALID-REQUEST>"
          },
          "errorDescription": {
            "type": "string",
            "example": "Validation Failure"
          },
          "errorList": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "action": {
                  "type": "string",
                  "example": "auth",
                  "description": "Holds the action that is being perfomed causing the error"
                },
                "errorCode": {
                  "type": "string",
                  "example": "AUTH-XXX"
                },
                "errorDescription": {
                  "type": "string",
                  "example": "AUTH xxx"
                },
                "errorDetails": {
                  "type": "array",
                  "description": "holds the downstream backend error details",
                  "items": {
                    "type": "object",
                    "properties": {
                      "system": {
                        "type": "string",
                        "example": "IDGRAPH"
                      },
                      "errorCode": {
                        "type": "string",
                        "example": "DTAPXXX"
                      },
                      "errorDescription": {
                        "type": "string",
                        "example": "DTAPXXX"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "requestBodies": {
      "AuthMethodsRequestBody": {
        "description": "Auth methods request body",
        "required": true,
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "intent": {
                  "type": "string",
                  "description": "intent of the order transaction ex: upgrade, add aline, swap"
                },
                "firstName": {
                  "type": "string",
                  "description": "firstname of the user authenticating for order transaction"
                },
                "lastName": {
                  "type": "string",
                  "description": "firstname of the user authenticating for order transaction"
                },
                "subscriberNumber": {
                  "type": "string"
                },
                "emailAddress": {
                  "type": "string"
                }
              },
              "required": [
                "intent",
                "firstName",
                "lastName",
                "subscriberNumber"
              ]
            }
          }
        }
      },
      "AuthRequestBody": {
        "description": "Auth request body",
        "required": true,
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "subscriberNumber": {
                  "type": "string"
                },
                "otp": {
                  "type": "object",
                  "properties": {
                    "pin": {
                      "type": "string",
                      "description": "pin value for authentication"
                    },
                    "deliveryMethod": {
                      "type": "string",
                      "description": "List of delivery channels (e.g., email, phone number) through which the OTP for PIN request can be sent"
                    }
                  }
                },
                "passcode": {
                  "type": "string"
                }
              },
              "required": [
                "subscriberNumber"
              ]
            }
          }
        }
      },
      "GenerateOtpRequestBody": {
        "description": "Generate OTP request body",
        "required": true,
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "subscriberNumber": {
                  "type": "string"
                },
                "deliveryMethods": {
                  "type": "array",
                  "description": "List of delivery channels (e.g., email, phone number) through which the OTP for PIN request can be sent",
                  "items": {
                    "type": "object",
                    "properties": {
                      "key": {
                        "type": "string",
                        "description": "Type of delivery method, such as 'email' or 'ctn' (cellular telephone number)"
                      },
                      "value": {
                        "type": "string",
                        "description": "The actual destination value for the delivery method, such as an email address or phone number"
                      }
                    }
                  }
                }
              },
              "required": [
                "subscriberNumber",
                "deliveryMethods"
              ]
            }
          }
        }
      }
    },
    "responses": {
      "AuthMethodsResponse": {
        "description": "Authentication methods returned",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "authMethods": {
                  "type": "array",
                  "items": {
                    "oneOf": [
                      {
                        "type": "object",
                        "properties": {
                          "otp": {
                            "type": "object",
                            "properties": {
                              "ctns": {
                                "type": "array",
                                "description": "list of ctns cpni eligible",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "email": {
                                "type": "string",
                                "description": "cpni eligibile email address"
                              }
                            }
                          }
                        }
                      },
                      {
                        "type": "object",
                        "properties": {
                          "passcode": {
                            "type": "string"
                          }
                        }
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      },
      "AuthSuccessResponse": {
        "description": "Authentication success",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "GenerateOtpResponse": {
        "description": "OTP generated successfully",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "expirationTimeStamp": {
                  "type": "string",
                  "format": "date-time",
                  "example": "2025-07-10T13:43:25Z",
                  "description": "Expiration timestamp in ISO 8601 format (GMT/UTC)"
                },
                "deliveryMethods": {
                  "type": "array",
                  "description": "Delivery method list",
                  "items": {
                    "type": "object",
                    "properties": {
                      "key": {
                        "type": "string",
                        "description": "email or ctn"
                      },
                      "value": {
                        "type": "string",
                        "description": "value of the deliverymethod"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}