> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.app/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth 2.0

> Use OAuth 2.0 to connect your app to HeyGen users on their behalf. Covers authorization flow, scopes, token exchange, refresh, and revocation with code.

This guide will walk you through connecting your app to HeyGen using OAuth 2.0. We'll use curl commands to demonstrate each step, making it easy to test the process. HeyGen uses the Authorization Code Flow with PKCE (Proof Key for Code Exchange) for added security.

## Prerequisites

Before you begin, ensure you have:

* Your HeyGen Client ID
* Your Redirect URI *(This will be provided by the Partnerships team after you have submitted your [Integration Intake form](https://form.typeform.com/to/m3EYcOaM))*

## Step 1: Initiate User Authorization

To begin the OAuth process, redirect the user to HeyGen's authorization URL. Create this URL (Replace the placeholders with your own values):

<CodeGroup>
  ```bash bash theme={null}
  https://app.heygen.com/oauth/authorize?client_id=YOUR_CLIENT_ID&state=RANDOM_STATE&redirect_uri=YOUR_REDIRECT_URI&code_challenge=CODE_CHALLENGE&code_challenge_method=S256&response_type=code
  ```
</CodeGroup>

* **YOUR\_CLIENT\_ID**: Client ID. (e.g., `abc123`)
* **RANDOM\_STATE**: A unique string to maintain state. (e.g., `xyz789`)
* **YOUR\_REDIRECT\_URI**: Your approved redirect URI, ensure URL-encoded. (e.g., `https://example.com/oauth/callback`)
* **CODE\_CHALLENGE** Corresponding `code_challenge` for a generated `code_verifier` using the PKCE flow (e.g. `E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM`). See: [RFC 7636 Appendix B](https://www.rfc-editor.org/rfc/rfc7636#appendix-B).

<Info>
  **Note:**

  You can generate a *code\_verifier* and *code\_challenge* using online PKCE tools or standard libraries (e.g., Node.js, Python).
</Info>

## Step 2: Handle the Authorization Callback

After approval, you'll be redirected to your Redirect URI with a `code` parameter. It'll look like this:

<CodeGroup>
  ```bash bash theme={null}
  https://yourapp.com/oauth/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE
  ```
</CodeGroup>

Verify that the state matches the one you sent in Step 1, then extract the `AUTHORIZATION_CODE`.

## Step 3: Exchange Authorization Code for Access Token

Exchange the authorization code for an access token using this curl command:

<CodeGroup>
  ```bash bash theme={null}
  curl -X POST https://api2.heygen.com/v1/oauth/token \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "code=AUTHORIZATION_CODE" \
    -d "client_id=YOUR_CLIENT_ID" \
    -d "grant_type=authorization_code" \
    -d "redirect_uri=YOUR_REDIRECT_URI" \
    -d "code_verifier=YOUR_CODE_VERIFIER"
  ```

  ```json Response theme={null}
  {
    "token_type": "Bearer",
    "access_token": "YyzWfeiqmklLsvzNsallQgUgfKHaNSnpv60BNgLGsC",
    "expires_in": 864000,
    "refresh_token": "dfU22fh6iD4aCkpy9GI32ulJXVe5eC8u4rt4SXedJHHich6L"
  }
  ```
</CodeGroup>

Save the `access_token` and `refresh_token` to use in the next steps.

## Step 4: Use the Access Token

Now you can make requests to HeyGen's API using the `Authorization` header with the Bearer scheme. Here's an example listing your avatar groups:

<CodeGroup>
  ```bash bash theme={null}
  curl -X GET https://api.heygen.com/v3/avatars \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```
</CodeGroup>

The **HeyGen API** endpoints support both authentication methods:

* **OAuth Access Tokens** — Use the `Authorization` header with the Bearer scheme. Format: `Authorization: Bearer YOUR_ACCESS_TOKEN`
* **API Keys** — Use the `X-Api-Key` header. Format: `X-Api-Key: YOUR_API_KEY`

## Step 5: Refresh the Access Token

Access tokens expire. Keep track of token expiration and refresh as needed. When the access token expires, use the refresh token to obtain a new one:

<CodeGroup>
  ```bash bash theme={null}
  curl -X POST https://api2.heygen.com/v1/oauth/refresh_token \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "client_id=YOUR_CLIENT_ID" \
    -d "grant_type=refresh_token" \
    -d "refresh_token=REFRESH_TOKEN"
  ```

  ```json Response theme={null}
  {
    "token_type": "Bearer",
    "access_token": "YyzWfeiqmklLsvzNsallQgUgfKHaNSnpv60BNgLGsC",
    "expires_in": 864000,
    "refresh_token": "dfU22fh6iD4aCkpy9GI32ulJXVe5eC8u4rt4SXedJHHich6L"
  }
  ```
</CodeGroup>

## Get User's Account Information

After successfully authenticating with HeyGen, you can retrieve account information — including remaining credits and billing details — using the `GET /v3/users/me` endpoint:

<CodeGroup>
  ```bash bash theme={null}
  curl -X GET https://api.heygen.com/v3/users/me \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```json Response theme={null}
  {
    "code": 100,
    "data": {
      "username": "jane_doe",
      "email": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "billing_type": "subscription",
      "subscription": {
        "plan": "enterprise",
        "credits": {
          "premium_credits": {
            "remaining": 250,
            "resets_at": "2026-05-01T00:00:00Z"
          },
          "add_on_credits": {
            "remaining": 50,
            "resets_at": null
          }
        }
      }
    },
    "message": null
  }
  ```
</CodeGroup>

Replace `YOUR_ACCESS_TOKEN` with the access token obtained during the OAuth process.

The `billing_type` field indicates which billing object is populated in the response:

| Billing Type   | Field          | Description                                                                                 |
| -------------- | -------------- | ------------------------------------------------------------------------------------------- |
| `wallet`       | `wallet`       | Prepaid balance in USD (or credits for Enterprise). Includes optional auto-reload settings. |
| `subscription` | `subscription` | Per-pool credit balances with plan tier and reset dates. Used with OAuth integration apps.  |
| `usage_based`  | `usage_based`  | Metered billing with current spending and optional spending cap.                            |

Only the field matching `billing_type` will be populated; the others will be `null`.

## Best Practices and Security Considerations

* Always use **HTTPS** for all OAuth-related requests.
* Store tokens securely and never expose them client-side.
* Implement token rotation and regularly refresh access tokens. If a request fails, check if the access token has expired.
* Validate the `state` parameter to prevent CSRF attacks.
* Use short-lived access tokens and long-lived refresh tokens.
* Implement proper error handling for token expiration and other OAuth-related errors.

***