diff --git a/src/@types/uia.ts b/src/@types/uia.ts
index e61142009..67e7a68ed 100644
--- a/src/@types/uia.ts
+++ b/src/@types/uia.ts
@@ -14,13 +14,13 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-import { IAuthData } from "../interactive-auth";
+import { IAuthDict, IAuthData } from "../interactive-auth";
 
 /**
  * Helper type to represent HTTP request body for a UIA enabled endpoint
  */
 export type UIARequest<T> = T & {
-    auth?: IAuthData;
+    auth?: IAuthDict;
 };
 
 /**
diff --git a/src/client.ts b/src/client.ts
index 59a6fd772..ea53b62f2 100644
--- a/src/client.ts
+++ b/src/client.ts
@@ -715,7 +715,7 @@ interface IJoinedMembersResponse {
 }
 
 export interface IRegisterRequestParams {
-    auth?: IAuthData;
+    auth?: IAuthDict;
     username?: string;
     password?: string;
     refresh_token?: boolean;
@@ -7857,7 +7857,7 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
      * @returns Promise which resolves: On success, the token response
      * or UIA auth data.
      */
-    public async requestLoginToken(auth?: IAuthData): Promise<UIAResponse<LoginTokenPostResponse>> {
+    public async requestLoginToken(auth?: IAuthDict): Promise<UIAResponse<LoginTokenPostResponse>> {
         // use capabilities to determine which revision of the MSC is being used
         const capabilities = await this.getCapabilities();
         // use r1 endpoint if capability is exposed otherwise use old r0 endpoint
@@ -8842,7 +8842,7 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
         return this.http.authedRequest(Method.Get, "/keys/changes", qps);
     }
 
-    public uploadDeviceSigningKeys(auth?: IAuthData, keys?: CrossSigningKeys): Promise<{}> {
+    public uploadDeviceSigningKeys(auth?: IAuthDict, keys?: CrossSigningKeys): Promise<{}> {
         // API returns empty object
         const data = Object.assign({}, keys);
         if (auth) Object.assign(data, { auth });
diff --git a/src/interactive-auth.ts b/src/interactive-auth.ts
index a222d8479..3b25e3cb7 100644
--- a/src/interactive-auth.ts
+++ b/src/interactive-auth.ts
@@ -44,7 +44,14 @@ export interface IStageStatus {
     error?: string;
 }
 
+/**
+ * Data returned in the body of a 401 response from a UIA endpoint.
+ *
+ * @see https://spec.matrix.org/v1.6/client-server-api/#user-interactive-api-in-the-rest-api
+ */
 export interface IAuthData {
+    // XXX: many of the fields here (`type`, `available_flows`, `required_stages`, etc) look like they
+    // shouldn't be here. They aren't in the spec and it's unclear what they are supposed to do. Be wary of using them.
     session?: string;
     type?: string;
     completed?: string[];
@@ -77,6 +84,11 @@ export enum AuthType {
     UnstableRegistrationToken = "org.matrix.msc3231.login.registration_token",
 }
 
+/**
+ * The parameters which are submitted as the `auth` dict in a UIA request
+ *
+ * @see https://spec.matrix.org/v1.6/client-server-api/#authentication-types
+ */
 export interface IAuthDict {
     // [key: string]: any;
     type?: string;
@@ -441,7 +453,7 @@ export class InteractiveAuth {
      *    This can be set to true for requests that just poll to see if auth has
      *    been completed elsewhere.
      */
-    private async doRequest(auth: IAuthData | null, background = false): Promise<void> {
+    private async doRequest(auth: IAuthDict | null, background = false): Promise<void> {
         try {
             const result = await this.requestCallback(auth, background);
             this.attemptAuthDeferred!.resolve(result);