{ "openapi": "3.1.2", "info": { "version": "1.0.2", "title": "Authentication", "description": "OpenAPI specification for external partners to authenticate and verify customers securely.", "contact": { "name": "Omni API Support", "email": "DL-OmniAdapter@att.com" } }, "servers": [ { "url": "https://partner.att.com/omni-svcs" } ], "tags": [ { "name": "Customer Management" } ], "paths": { "/v1/identity/auth-methods": { "post": { "tags": [ "Customer Management" ], "x-tags": [ "Fiber-Change-Consumer", "Fiber-Move-Consumer", "Wireless" ], "description": "Returns a list of supported authentication methods (e.g., OTP, passcode) for a customer based on the provided intent and Customer details", "summary": "Retrieve available authentication methods", "operationId": "getAuthMethods", "requestBody": { "description": "Auth methods request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthMethodsRequestBody" }, "examples": { "fiberFlow": { "summary": "Fiber flow authentication methods request", "description": "Example of requesting authentication methods for a fiber customer", "value": { "firstName": "John", "lastName": "Doe", "canBeReachedNumber": "2145551234", "emailAddress": "john.doe@example.com", "billingAccountNumber": "987654321" } }, "wirelessFlow": { "summary": "Wireless flow authentication methods request", "description": "Example of requesting authentication methods for a wireless customer", "value": { "firstName": "Jane", "lastName": "Smith", "subscriberNumber": "2145559999", "emailAddress": "jane.smith@example.com" } } } } } }, "responses": { "200": { "description": "Authentication methods returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthMethodsResponse" }, "examples": { "fiberAuthMethodsResponse": { "summary": "Fiber authentication methods response", "description": "Example response showing available authentication methods for a fiber customer", "value": { "authMethods": [ { "passcode": "true", "last4SSN": "true" } ] } }, "bsseFiberAuthMethodsResponse": { "summary": "Fiber authentication methods response", "description": "Example response showing available authentication methods for a fiber customer", "value": { "authMethods": [ { "passcode": "true" } ] } }, "wirelessAuthMethodsResponse": { "summary": "Wireless authentication methods response", "description": "Example response showing available authentication methods for a wireless customer", "value": { "authMethods": [ { "otp": { "ctns": [ "1234567890" ] }, "passcode": "true" } ] } } } } } }, "400": { "description": "Bad request - Missing fields, Invalid input data, validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WrappedPartnerServiceError" }, "examples": { "MissingFields": { "summary": "Missing fields", "value": { "error": { "errorId": "EXTCUSTMGMT-AUTHMETHOD-0001", "message": "Required fields are missing", "errorSystemId": "extpartnercustmgmtms", "details": [ { "code": "INT-0011", "message": "First and Last name is required" } ] } } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WrappedPartnerServiceError" }, "examples": { "SystemError": { "summary": "System Error", "value": { "error": { "errorId": "EXTCUSTMGMT-AUTHMETHOD-002", "message": "Downstream service error occurred", "errorSystemId": "extpartnercustmgmtms", "details": [ { "code": "INT-0002", "message": "Internal exception occurred while processing the request" } ] } } } } } } } } } }, "/v1/customer/auth": { "post": { "tags": [ "Customer Management" ], "description": "Validates customer credentials and returns the authentication status along with detailed error information if applicable.", "summary": "Authenticate customer using selected authentication method", "operationId": "authenticateCustomer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthRequestBody" }, "examples": { "fiberAuthWithPasscode": { "summary": "Fiber authentication using passcode", "description": "Example of authenticating a fiber customer using a passcode", "x-tags": [ "Fiber-Change-Consumer", "Fiber-Move-Consumer" ], "value": { "partnerCustomerUUID": "uuid-customer1 (optional)", "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "canBeReachedNumber": "2145551234", "billingAccountNumber": "987654321", "serviceAddressId": "12345", "passcode": "jwe:eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ..." } }, "fiberAuthWithLast4SSN": { "summary": "Fiber authentication using last 4 SSN", "description": "Example of authenticating a fiber customer using last 4 digits of SSN", "x-tags": [ "Fiber-Change-Consumer", "Fiber-Move-Consumer" ], "value": { "partnerCustomerUUID": "uuid-customer1 (optional)", "firstName": "Jane", "lastName": "Smith", "email": "jane.smith@example.com", "canBeReachedNumber": "2145555678", "billingAccountNumber": "123456789", "serviceAddressId": "67890", "last4SSN": "jwe:eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ..." } } } } } }, "responses": { "200": { "description": "Authentication successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSuccessResponse" } } }, "headers": { "X-ATT-Token": { "description": "The new JWT token created for the session.", "schema": { "type": "string" } } } }, "400": { "description": "Bad Request - Invalid input or missing required fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WrappedPartnerServiceError" }, "examples": { "InvalidPasscodeMethod": { "value": { "error": { "errorId": "CUSTMGMT_AUTH_INVALID-REQUEST-001", "message": "Passcode authentication method is not allowed for this account." } } }, "InvalidLast4SSNMethod": { "value": { "error": { "errorId": "CUSTMGMT_AUTH_INVALID-REQUEST-001", "message": "Last 4 SSN authentication method is not allowed for this account." } } }, "InvalidOTPNMethod": { "value": { "error": { "errorId": "CUSTMGMT_AUTH_INVALID-REQUEST-001", "message": "OTP authentication method is not allowed for this account." } } } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WrappedPartnerServiceError" }, "example": { "error": { "errorId": "CUSTMGMT_AUTH_FAILED-001", "message": "Authentication failed due to invalid credentials.", "details": [ { "code": "AUTH-001", "message": "The provided credentials are incorrect." } ] } } } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WrappedPartnerServiceError" } } } } } } } }, "components": { "schemas": { "AuthSuccessResponse": { "type": "object", "properties": { "status": { "type": "string", "description": "Authentication status (e.g., SUCCESS ).", "example": "SUCCESS" } } }, "AuthMethodsRequestBody": { "type": "object", "properties": { "intent": { "type": "string", "description": "Intent of the order transaction (e.g., upgrade, add a line, swap)." }, "firstName": { "type": "string", "description": "Customer first name." }, "lastName": { "type": "string", "description": "Customer last name." }, "subscriberNumber": { "type": "string", "description": "Wireless subscriber number (CTN). Required for wireless flows." }, "emailAddress": { "type": "string", "description": "Email address associated with the account/customer." }, "canBeReachedNumber": { "type": "string", "description": "Contact phone number for OTP delivery (used for fiber)." }, "billingAccountNumber": { "type": "string", "description": "Billing account number. Required for broadband authentication." } }, "required": [ "firstName", "lastName" ] }, "AuthRequestBody": { "type": "object", "properties": { "partnerCustomerUUID": { "type": "string", "description": "Partner-provided unique customer identifier." }, "firstName": { "type": "string", "description": "Customer first name." }, "lastName": { "type": "string", "description": "Customer last name." }, "email": { "type": "string", "format": "email", "description": "Customer email address." }, "canBeReachedNumber": { "type": "string", "description": "Contact phone number" }, "subscriberNumber": { "type": "string", "description": "Wireless subscriber number (CTN). Required for wireless flows." }, "serviceAddressId": { "type": "string", "description": "Service address identifier. Required for broadband authentication." }, "billingAccountNumber": { "type": "string", "description": "Billing account number. Required for broadband authentication." }, "otp": { "type": "object", "properties": { "pin": { "type": "string", "description": "One-time passcode (PIN) value used for authentication." }, "deliveryMethod": { "type": "string", "description": "Delivery channel used to send the OTP (e.g., email, ctn)." } } }, "passcode": { "type": "string", "description": "Account passcode for authentication. Must be sent in JWE (JSON Web Encryption) format." }, "last4SSN": { "type": "string", "description": "Last four digits of SSN for authentication. Must be sent in JWE (JSON Web Encryption) format." } } }, "GenerateOtpRequestBody": { "type": "object", "properties": { "subscriberNumber": { "type": "string", "description": "Wireless subscriber number (CTN) for which the OTP is generated." }, "deliveryMethods": { "type": "array", "description": "List of delivery channels (e.g., email, ctn) through which the OTP can be sent.", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Delivery method key (e.g., 'email' or 'ctn' for cellular telephone number)." }, "value": { "type": "string", "description": "Destination value for the delivery method (email address or phone number)." } } } } }, "required": [ "subscriberNumber", "deliveryMethods" ] }, "AuthMethodsResponse": { "type": "object", "properties": { "authMethods": { "type": "array", "description": "Available authentication methods for the customer based on intent and provided details.", "items": { "type": "object", "properties": { "otp": { "type": "object", "properties": { "ctns": { "type": "array", "description": "List of CPNI-eligible wireless numbers (CTNs).", "items": { "type": "string" } }, "email": { "type": "string", "description": "CPNI-eligible email address." } } }, "passcode": { "type": "string", "description": "Indicates that passcode-based authentication is supported." }, "last4SSN": { "type": "string", "description": "Indicates that last 4 SSN-based authentication is supported." } } } } } }, "GenerateOtpResponse": { "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 methods used to deliver the OTP.", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Delivery method key ('email' or 'ctn')." }, "value": { "type": "string", "description": "Destination value (email address or phone number)." } } } } } }, "PartnerServiceError": { "type": "object", "properties": { "errorId": { "type": "string", "example": "Top level error code" }, "message": { "type": "string", "example": "Top level error message" }, "errorSystemId": { "type": "string", "example": "System name" }, "details": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "Detail code 1" }, "message": { "type": "string", "example": "Detail message 1" } } } } } }, "WrappedPartnerServiceError": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/PartnerServiceError" } } } } } }