Skip to main content
Version: 1.x.x

Auth API

Once auth configurations are completed, you can use the apis below to trigger auth flows or make api requests.

quip.apps.auth​

Function(authName: string) => quip.apps.Auth | undefined

Returns the auth instance if there's one corresponding to the given name and undefined otherwise. Depending on the auth config's type, the returned instance may be a quip.apps.UrlAuth or quip.apps.OAuth2

Example​


const auth = quip.apps.auth("gdrive") as quip.apps.OAuth2;

quip.apps.OAuth2​

This is the object quip.apps.auth will return if the auth config has the type OAUTH2.

quip.apps.OAuth2.prototype​

login​

Function(params?: {[key: string]: string}) => Promise<boolean>

Triggers the login flow, which happens in a pop up window on web and in overlay windows on native apps. The window will close automatically if at the end of login flow.

You may pass an object containing custom query parameters to be sent to the login url during the login flow.

Returns a promise that resolves if the login is successful. If there is an error, the promise will throw.

Example​


const auth = quip.apps.auth("gdrive") as quip.apps.OAuth2;
try {
    const loginResponse = await auth.login({
        "access_type": "offline",
        "prompt": "consent",
        "scope": "https://www.googleapis.com/auth/drive.readonly",
    });
    console.log("Successfully logged in")
} catch (error) {
    console.error("Login failed:", error.message);
}

isLoggedIn​

Function() => boolean

Returns a boolean value that represents whether the user is logged in.

Example​


const auth = quip.apps.auth("gdrive") as quip.apps.OAuth2;
auth.isLoggedIn();
// returns true or false

getTokenResponse​

Function() => {[key: string]: string}

Returns the token response returned by the OAuth2 token endpoint during the login flow.

Example​


const auth = quip.apps.auth("gdrive") as quip.apps.OAuth2;
auth.getTokenResponse();
// returns {
//     access_token: "...",
//     expires: 3600,
//     token: "Bearer"
// }

getTokenResponseParam​

Function(paramName: string) => string | undefined

String name of the field you want to query.

Returns the field in corresponding to the paramName in the token response.

Example​


const auth = quip.apps.auth("gdrive") as quip.apps.OAuth2;
auth.getTokenResponseParam("access_token");
// returns "ya29..."

refreshToken​

Function() => Promise<quip.HttpResponse>

Returns a promise that resolves to a quip.HttpResponse object containing the result of the server's attempt to refresh the user's access token. It's required that Refresh Token Strategy is set to a value other than NONE.

Example​


const auth = quip.apps.auth("gdrive") as quip.apps.OAuth2;
const response = await auth.refreshToken();
console.log("response:", response.status, response.json());

logout​

Function() => Promise<quip.HttpResponse>

Returns a promise that resolves to a quip.HttpResponse object containing the result of the server's attempt to log out.

Example​


const auth = quip.apps.auth("gdrive") as quip.apps.OAuth2;
const response = await auth.logout();
console.log("response:", response.status, response.json());

request​

Function<T = Object>(params: quip.OAuthRequestParams) => Promise<quip.HttpResponse<T>>

Apps that have configured Proxy API Domains can use this method to make api calls to third-party platforms.

Returns a promise that resolves to an quip.HttpResponse object containing the result of the server's attempt to log out.

Example​


const auth = quip.apps.auth("gdrive") as quip.apps.OAuth2;
try {
    const response = await auth.request({
        "https://www.googleapis.com/drive/files/root"
    });
    const body = response.json();
    console.log(JSON.stringify(body, null, 4));
} catch (error) {
    console.log("error fetching:", error.message);
}

quip.apps.UrlAuth​

This is the object quip.apps.auth will return if the auth config has the type URL.

quip.apps.UrlAuth.prototype​

login​

Function(params?: {[key: string]: string}) => Promise<boolean>

Triggers the login flow, which happens in a pop up window on web and in overlay windows on native apps. The window will close automatically if at the end of login flow.

You may pass an object containing custom query parameters to be sent to the login url during the login flow.

Returns a promise that resolves if the login is successful. If there is an error, the promise will throw.

Example​


const auth = quip.apps.auth("intranet") as quip.apps.OAuth2;
try {
    const loginResponse = await auth.login({ param: "value" });
    console.log("Successfully logged in")
} catch (error) {
    console.error("Login failed:", error.message);
}

Making Cross Origin AJAX Requests​

Once the user is successfully logged in, a cookie should be set on the domain of the login url. To make a Cross Origin AJAX request using the cookie credentials, you can use fetch.

Example

fetch("https://intranet.company.com/api", {
    mode: "cors",
    credentials: "include"
}).then(response => response.json());

quip.OAuthRequestParams​

url​

required

string

String url that matches at least one of the Proxy API Domains. If no domain matches, an error will be thrown.

method​

optional

("GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE") = "GET"

String http method. Defaults to GET

query​

optional

{[key: string]: string}

Object containing query parameters to be appended to the url

headers​

optional

{[key: string]: string}

Object containing custom http headers to be sent with the request.

data​

optional

{[key: string]: any}

Object containing data to be sent in the body of the request. Will be serialized as JSON.

quip.HttpResponse<T = Object>​

A class representing an HTTP response. Accepts a generic parameter allowing strong typing of response bodies.

url​

string

The URL this response is from

status​

number

An HTTP status code for this response

statusText​

string

A text representation of the status of this request.

headers​

quip.HttpHeaders

Response headers for this request.

ok​

boolean

A boolean representing if this request was ok or not.

text​

Function() => string

Returns the raw body for this request as a string.

json​

Function() => T

Returns a parsed body for this request. Useful for retaining type safety.

toJSON​

Function() => {
    url: string,
    body: string,
    status: number,
    statusText: string,
    headers: {[key: string]: string},
}

Returns a JSON representation of the entire http response, including all properties.

quip.HttpHeaders​

get​

Function(name: string) => string | null

Gets a header value by name, or null if it is not present.

has​

Function(name: string) => boolean

Returns true if the provided header exists, otherwise returns false.