API: requestExternalAuthorization

Description

The requestExternalAuthorization method enables external applications to bypass the SmarterU log in screen to provide a user access the SmarterU interface. Any users except account administrators and owners can be logged in via this method. 

API calls for this method must be made from pre-authorized IP addresses specified for your account. This is to prevent unauthorized access to SmarterU accounts. If too many unsuccessful requests are made, all API calls will be blocked until reactivated by an account administrator. 

If a call of the requestExternalAuthorization method is successful, the method will return two keys (i.e., AuthKey and RequestKey). These keys are only active and valid for 60 seconds. After 60 seconds, the user will need to be re-authorized. 

Once the user is directed to SmarterU using the URL specified in the API response's RedirectPath tag, the keys will be deactivated and the user will be logged into SmarterU. 

Who Has Access

Administrators and owners have access to the requestExternalAuthorization method.

API Call XML Package

<SmarterU>
   <AccountAPI></AccountAPI>
   <UserAPI></UserAPI>
   <Method>requestExternalAuthorization</Method>
   <Parameters>
      <Security>
         <Email><![CDATA[]]></Email>
            - OR -
         <EmployeeID><![CDATA[]]></EmployeeID>
      </Security>
   </Parameters>
</SmarterU>

Security Tag Group

The Security tag group is a container for the user to be authenticated. 

<Security>
   <Email><![CDATA[]]></Email>
      - OR -
   <EmployeeID><![CDATA[]]></EmployeeID>
</Security>

The Security tag may contain the following.

Email

The primary email address of the user being authenticated. This tag is mutually exclusive with the EmployeeID tag. This is the Email returned by the getUser and listUsers methods.

EmployeeID

The employee ID of the user being authenticated. This tag is mutually exclusive with the Email tag. This is the EmployeeID returned by the getUser and listUsers methods.

API Response XML Package

The API response XML package will always include a Result, Info, and Errors tag.

<SmarterU>
   <Result></Result>
   <Info>
      <AuthKey></AuthKey>
      <RequestKey></RequestKey>
      <RedirectPath></RedirectPath>
   </Info>      
   <Errors>
      <Error>
         <ErrorID></ErrorID>
         <ErrorMessage></ErrorMessage>
      </Error>
   </Errors>
</SmarterU>

The response may also contain the following. 

AuthKey

The one-time authorization key used to authenticate a user within SmarterU. This key will expire within 60 seconds of the request.

RequestKey

The unique identifier of the authorization request. This key must be used in tandem with the AuthKey to have a user authenticated in SmarterU.

RedirectPath

The full path to redirect the user to SmarterU to finalize the authentication process. This URL will change based upon the settings of your SmarterU account to reflect whether you're using a CNAME entry or a keyword for a customized login portal.

Error Codes