API: requestExternalAuthorization
  • 2 Minutes to read
  • Dark
    Light

API: requestExternalAuthorization

  • Dark
    Light

Article summary

  • Starting June 1, 2022, SmarterU will require all API calls to POST to HTTPS. Any POST to HTTP will result in the SU:01 error (i.e., No POST data detected.).
  • If you are viewing the help in a language other than English, please change your language to English before copying and pasting any code. All API attributes and functions are in English.
  • Tags are required unless specified.

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. 

Administrators and owners must log into SmarterU directly.

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 requestExternalAuthorization method can only have one Security tag.

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

Error CodeMessage
REA:01
The email address provided is not valid.
REA:02
The employee ID provided is not valid.
REA:03
The user's permissions do not allow for authentication in this method.
REA:04
The user was not found in the provided account.
REA:05
This method cannot be accessed from your location.

Was this article helpful?