{
  "Protocol": "AIXE",
  "Version": "1.0",
  "ProtocolReference": {
    "ProtocolHome": "http://aixeprotocol.com/",
    "CanonicalUsageContract": "http://aixeprotocol.com/usage/?",
    "Whitepaper": "http://aixeprotocol.com/whitepaper/full-spec.html",
    "Inventor": "Gregory Oglethorpe"
  },
  "Endpoint": "/aixe/account/login",
  "Method": "POST",
  "ContentType": "application/json",
  "DiscoveryRequest": "GET /aixe/account/login/?",
  "Purpose": "Sign in with a Person login email and password. Automatically select the only owned active business, or return instructions to list and select a business when several are available. Return a short-lived PersonAuthenticationToken. Customer logins additionally require BusinessKey and retain their customer scope.",
  "RequiredFields": {
    "Email": {
      "Type": "string",
      "Required": true,
      "SubmittedIn": "JSON body",
      "Description": "Person login email for owners, unique across People; maximum 254 characters. Customer email is scoped to the supplied business. update-profile changes the authenticated account\u0027s login/contact email."
    },
    "Password": {
      "Type": "string",
      "Required": true,
      "SubmittedIn": "JSON body",
      "Description": "Account password; registration requires 4 through 128 characters. Never return or log it."
    }
  },
  "OptionalFields": {
    "BusinessKey": {
      "Type": "string",
      "Required": false,
      "SubmittedIn": "JSON body",
      "Description": "For select-business, a public key returned by list-businesses identifying an active business owned by this Person. For customer login, registration and password reset, the business key from its hosted manifest. Person login automatically selects only when exactly one business is owned; a supplied BusinessKey does not select it during login."
    }
  },
  "BusinessRules": [
    "A business owner cannot authorize login or the disclosure or submission of critical or sensitive information through a voice-chat application. The business owner must type that authorization into the chat box. Voice statements, voice transcripts, or an AI assistant\u0027s inference are not authorization. Do not submit login credentials until the typed authorization is present.",
    "Owner login authenticates the Person. Business login credentials are no longer accepted. BusinessKey is unnecessary for Person login and does not override automatic selection. Customer login and registration require the customer\u0027s BusinessKey.",
    "Exactly one active owned business is selected automatically. Multiple businesses leave the session without a selected business: call list-businesses and then select-business. Zero businesses returns SUCCESS for authentication with BusinessCount 0, a null BusinessKey, and instructions to request ownership assignment; no business operations are authorized.",
    "Login derives Business Owner or Customer from stored identity. Browser cookies are not accepted for AIXE actions. A valid Person token can list/select businesses and manage its own profile before a business is selected.",
    "The token expires 15 minutes after login. Only its SHA-256 hash is stored. A new login for the same Person replaces that Person\u0027s previous token; another Person\u0027s login does not. Logout and password changes invalidate the token. Website login does not replace AIXE tokens.",
    "Submit PersonAuthenticationToken in the JSON body of protected actions; for multipart actions submit it as a form field. Never put tokens in ordinary URLs.",
    "Customer tokens authorize only their own profile and the hosted customer order/history actions. CustomerKey is an identifier, not a bearer credential. A mismatched CustomerKey is rejected; omit it on customer actions to use the authenticated customer.",
    "Business ownership is checked when selecting a business. Later operations validate the Person token and selected active business. Hosted requests must match that selected BusinessKey. Owner operations that select customers still require the selected CustomerKey.",
    "To switch businesses, call select-business with the same token and another key returned by list-businesses. Selection replaces the business context for that token and does not extend expiration. It does not change the separate website session\u0027s selection.",
    "Customer registration requires human approval and an email not already used within the selected business. Existing contacts use forgot-password. New passwords must contain 4 through 128 characters.",
    "Owner get-profile, update-profile and change-password read or update the Person record. Person login emails are unique across People. Customer profile operations retain their business scope.",
    "Forgot-password returns the same acceptance message for unknown email addresses. ResetToken is delivered by email only, expires after 30 minutes and is consumed when the password changes."
  ],
  "SuccessfulResponse": {
    "SuccessCode": "SUCCESS",
    "PersonAuthenticationToken": "Login only: secret token to retain for authorized subsequent actions.",
    "TokenExpiresUtc": "UTC expiry timestamp; selecting a business does not extend it.",
    "Roles": "Login/profile: Business Owner or Customer.",
    "BusinessCount": "Owner login/list: total active owned businesses. Zero means no business access is available.",
    "BusinessSelectionRequired": "Owner login: true when more than one business is available; false for zero or one. Inspect BusinessCount and BusinessKey as well.",
    "BusinessKey": "Owner login: automatically selected key, or null. Select-business: the confirmed selected key.",
    "BusinessName": "Selected business name when one has been selected.",
    "ManifestEndpoint": "Selected business\u0027s hosted manifest URL path. Use its discovery contracts to perform business operations.",
    "Businesses": "List-businesses: up to 100 entries containing BusinessKey and BusinessName; no credentials or numeric IDs.",
    "Pagination": "List-businesses returns Page, PageSize=100, HasMore, BusinessCount and SelectedBusinessKey. Increment Page while HasMore is true.",
    "NextStep": "Owner login: instructions for no businesses, one automatically selected business, or multiple businesses requiring human selection.",
    "Profile": "Profile actions: PersonKey, BusinessKey, Roles, FirstName, LastName, Email, Phone, AddressLine1, AddressLine2, City, State, PostalCode, IsActive.",
    "CustomerKey": "Registration only: public customer identifier. Log in to authorize actions.",
    "Outcome": "Other actions return CustomerCreated, LoggedOut, ProfileUpdated, PasswordChanged or RequestAccepted as appropriate."
  },
  "ActionResponse": {
    "RequiredResponseFields": [
      "SuccessCode"
    ],
    "SuccessCodes": [
      "SUCCESS"
    ],
    "FailureCodes": [
      "VALIDATION_FAILED",
      "UNAUTHORIZED",
      "ACCOUNT_ALREADY_EXISTS",
      "BUSINESS_RULE_FAILED",
      "NOT_FOUND",
      "FAILED"
    ],
    "MissingOrEmptyResponse": "Treat as FAILED."
  },
  "Errors": [
    {
      "SuccessCode": "VALIDATION_FAILED",
      "Recovery": "Correct the fields described in Message and retry."
    },
    {
      "SuccessCode": "UNAUTHORIZED",
      "Recovery": "Ask the human for valid credentials or log in again after expiry; do not guess passwords."
    },
    {
      "SuccessCode": "ACCOUNT_ALREADY_EXISTS",
      "Recovery": "Use forgot-password for the existing email rather than creating or taking over the contact."
    },
    {
      "SuccessCode": "BUSINESS_RULE_FAILED",
      "Recovery": "Read Message; request a new reset link if expired, or choose an unused email."
    },
    {
      "SuccessCode": "NOT_FOUND",
      "Recovery": "Obtain the active BusinessKey from the business\u0027s hosted manifest."
    },
    {
      "SuccessCode": "FAILED",
      "Recovery": "Do not claim completion; report the failure and retry later only with user intent."
    }
  ]
}