---
title: "API: requestExternalAuthorization"
slug: "api-requestexternalauthorization"
tags: ["single sign-on"]
updated: 2022-09-12T18:26:48Z
published: 2022-09-12T18:26:48Z
canonical: "support.smarteru.com/api-requestexternalauthorization"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://support.smarteru.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API: requestExternalAuthorization

- 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](https://support.smarteru.com/v1/docs/user-profile-information#access-level) must log into SmarterU directly.

API calls for this method must be made from [pre-authorized IP addresses specified for your account](/v1/docs/account-api-setup#api-allowed-sources). 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](/v1/docs/api-requestexternalauthorization#api-call-xml-package) of the requestExternalAuthorization method is successful, the method will return two keys (i.e., [AuthKey and RequestKey](/v1/docs/api-requestexternalauthorization#api-response-xml-package)). 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](/v1/docs/api-requestexternalauthorization#redirectpath), the keys will be deactivated and the user will be logged into SmarterU.

## Who Has Access

[Administrators and owners](https://support.smarteru.com/v1/docs/user-profile-information#access-level) have access to the requestExternalAuthorization method.

## API Call XML Package

```markup
<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.

```markup
<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](/v1/docs/api-requestexternalauthorization#employeeid). This is the Email returned by the [getUser](/v1/docs/api-getuser) and [listUsers](/v1/docs/api-listusers) methods.

### EmployeeID

The employee ID of the user being authenticated. This tag is mutually exclusive with the [Email tag](/v1/docs/api-requestexternalauthorization#email). This is the EmployeeID returned by the [getUser](/v1/docs/api-getuser) and [listUsers](/v1/docs/api-listusers) methods.

## API Response XML Package

The [API response XML package](/v1/docs/api-response-xml-package) will always include a Result, Info, and [Errors](/v1/docs/api-requestexternalauthorization#error-codes) tag.

```markup
<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](/v1/docs/api-requestexternalauthorization#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](/v1/docs/account-portals#cname) or a [keyword](/v1/docs/account-portals#keyword) for a customized login portal.

## Error Codes

| Error Code | Message |
| --- | --- |
| 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. |

## Related

- [Account: API Setup](/account-api-setup.md)
- [Account: Portals](/account-portals.md)
- [API: getUser](/api-getuser.md)
- [API: listUsers](/api-listusers.md)
- [External Authorization (SSO)](/external-authorization-sso.md)