Recall-Managed OAuth

The last step in the Zoom OAuth integration process is to actually direct your users through the OAuth authorization flow.

Since Recall-managed OAuth manages access and refresh tokens for you, the only two implementation steps necessary are:

1. Directing the user to a Zoom OAuth URL
2. Creating a Zoom OAuth Credential in Recall using the code received in the OAuth callback

📘

For demonstration purposes, we will abstract some of this implementation and pass the authorization code manually through an API request to Recall.

In production, this should be done programmatically in your app, for example by requesting Zoom OAuth permission as part of your onboarding flow, or having your users click a button in your app to connect their Zoom account.

Registering A Redirect URL

Under Basic Information, add an OAuth Redirect URL (the OAuth Allow List will be automatically updated).

For testing purposes, this can be any URL, though it can be convenient to use a placeholder for a server endpoint that will handle passing this authorization code to Recall for when you implement the end to end user flow.

In the example below, this is set to: http://localhost:3000/oauth-callback/zoom

Constructing a Zoom OAuth URL

A Zoom OAuth URL is the URL that you'll be navigating your users to, for them to grant the permissions. For example, you might have a button that says "Connect Zoom", that redirects your user to the OAuth URL.

You can generate the URL using the following code:

function generateAuthUrl(redirectUri: string, zoomAppClientId: string): string {
    const baseUrl = "https://zoom.us/oauth/authorize";
    const queryParams = {
        "response_type": "code",
        "redirect_uri": redirectUri,
        "client_id": zoomAppClientId,
    };
    const queryString = new URLSearchParams(queryParams).toString();
    return `${baseUrl}?${queryString}`;
}

from urllib.parse import urlencode
def generate_auth_url(redirect_uri, client_id):
    base_url = "https://zoom.us/oauth/authorize"
    query_params = {
        "response_type": "code",
        "redirect_uri": redirect_uri,
        "client_id": client_id,
    }
    return base_url + "?" + urlencode(query_params)

The redirect_uri should exactly match the configured OAuth redirect URL step above.

After calling this function, you should get a URL that looks like the following: https://zoom.us/oauth/authorize?response_type=code&redirect_uri=https%3A%2F%2Flocalhost%3A8000&client_id=YOUR-CLIENT-ID-HERE

Paste this URL into your web browser, and grant the permission when prompted by Zoom.

Obtaining the OAuth Code

After clicking "Allow", you will be redirected to the redirect_uri configured in the previous step.

Since we don't yet have a server running to process this request yet, you will see a page similar to below:

This is expected behavior. You now want to look at the URL in your web browser, which should look something like the following: https://localhost:3000/oauth-callback/zoom?code=JFiSLNVIEejhfiJLmU6AuTnKZQ

The value in the code query parameter is your OAuth code. Save this for the next step.

🚧

If you're getting "Invalid redirect", check your Redirect URI

The redirect URI specified in the query parameter must match exactly the redirect URI registered in the Zoom OAuth App console, including any trailing slashes.

Calling the Recall API

Now that the user has authorized their account, we can use the OAuth code to register them in the Recall API by calling the Create Zoom OAuth Credential endpoint.

$ curl -X POST https://api.recall.ai/api/v2/zoom-oauth-credentials/
	-H 'Authorization: ${RECALL_API_KEY}'  
 	-H 'Content-Type: application/json'  
  -d '{  
    "oauth_app": ${RECALL_ZOOM_OAUTH_APP_ID},  
    "authorization_code": {  
      "code": "JFiSLNVIEejhfiJLmU6AuTnKZQ",
      "redirect_uri": ${ZOOM_OAUTH_REDIRECT_URI},  
    }  
  }'

Example 201 response:

{  
  "id":"dadcc9c3-2a6d-4f9a-9467-ff3a2b02a82f",  
  "oauth_app":"2d40abfe-c692-4723-b26f-869ebfbde4cf",  
  "user_id":"...",                   // Populated for User-managed apps
  "account_id": "...",               // Populated for Admin-managed apps
  "access_token_callback_url": null, // Not applicable, only used for customer-managed OAuth
  "created_at":"2024-04-24T06:38:38.879706Z"  
}

🚧

If you're getting "Invalid Grant", check your Redirect URI

The redirect URI sent in this request must match EXACTLY the redirect URI registered in the Zoom OAuth App console, including any trailing slashes.

Handling deauthorization and reauthorization

📘

A disconnected Zoom user will not be reflected immediately

When a Zoom user revokes their OAuth permissions for your app, Recall doesn't know this immediately.

Since Recall doesn't get notified when a user revokes their OAuth permissions, the user's credentials will still exist in Recall unless you explicitly delete them.

This can cause issues when a user tries to re-authenticate to your app, since their credentials will already exist.

Currently, you must handle this case by recreating the credentials if they already exist.

In this case, your logic directing a user through the OAuth flow should add a code path for handling a 400 response from Create Zoom OAuth Credential with a conflicting_zoom_account_id in the body:

{
  "detail": "A Zoom OAuth Credential already exists for this OAuth App and Zoom account(account_id: ...). A Zoom OAuth App can have at most one Zoom OAuth Credential registered per authorized Zoom account. Please delete the existing Zoom OAuth Credential for Zoom account(account_id: ...) and try again.",
  "conflicting_zoom_account_id": "..."
}

You can then:

1. Delete the credentials using the conflicting_zoom_account_id
2. Recreate the credentials