API Documentation

Method Generate_PIN

This newer version of Generate_PIN is used to create a Personal Identification Number (PIN) for Two-Factor Authentication. It replaces component Login's method Generate_PIN, which has been deprecated.

Currently, logging into any other web service requires only the CLSUsername and CLSPassword input parameters. Soon however, other web services also require a third parameter, CLSPIN. After a period of time of getting used to this process, CLSPIN will become mandatory in all web services.

Pass the CLSUsername and CLSPassword of the CLS account that will use the PIN. If the account that will be using the PIN is of type Application-to-Application (INTERNAL ONLY), the response to a successful call will contain the PIN itself. For all other account types, the PIN will be sent to the user’s email address and/or phone number(s) saved in the account profile. The user can then provide the PIN to any subsequent web service that may require it.

SOAP Component: https://catweb.sba.gov/cls/ws/auth.wsdl
SOAP Method: AuthFromStruct, only input is structure Inputs
Or: AuthFromString, only input is JSON string InputString that decodes to a structure
REST Component: /rest/account/auth
REST Method: /rest/account/auth/AuthFromStruct, only input is structure InputsAuthStruct
Or: /rest/account/auth/AuthFromString, only input is JSON string InputsAuthString
Keys of the Input Structure:
  • MethodNamePhysical
    		•  Mandatory. Must be “Generate_PIN”.
  • CLSUsername
    		•  Mandatory. Must be the user’s CLS login username
  • CLSPassword
    		•  Mandatory. Must be the user’s CLS login password.
  • ContactMode
    		•  Optional. Can be “text”, “voice”, or “email”. Determines how to send the generated PIN. If this field is not given, the PIN will be sent to all ContactModes that have been successfully used before.
    Keys of the Output Structure:
  • ErrorMessageEnglish
    		•  Should be nullstring. If not, a generally-worded error message.
  • ErrorMessageTechnical
    		•  Should be nullstring. If not, a more helpful error message, but scarier to some users.
  • PasswordUpdateRequired
    		•  “Yes”, “No”, number of days till expiration or “TBD” (prior to validating login).
  • ResponseData
    		•  The extracted XML in SBA_ETran.orig.xsd format (for the version requested).
  • Successful
    		•  “Yes” or “No”. If “No”, see ErrorMessageEnglish and ErrorMessageTechnical.