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)

Step 1: Initiate User Authorization

To begin the OAuth process, redirect the user to HeyGen's authorization URL. Create this URL (replace the capitalized parts with your info):

https://app.heygen.com/oauth/authorize?client_id=YOUR_CLIENT_ID&state=RANDOM_STATE&redirect_uri=YOUR_REDIRECT_URI&response_type=code

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://yourapp.com/oauth/callback)

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:

https://yourapp.com/oauth/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE

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:

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"

{
  "token_type": "Bearer",
  "access_token": "YyzWfeiqmklLsvzNsallQgUgfKHaNSnpv60BNgLGsC",
  "expires_in": 864000,
  "refresh_token": "dfU22fh6iD4aCkpy9GI32ulJXVe5eC8u4rt4SXedJHHich6L"
}

Save the access_token and refresh_token - you'll need them!

Step 4: Use the Access Token

Now you can make requests to HeyGen's API. Here's an example:

curl -X GET https://api.heygen.com/v1/some-endpoint \
  -H "Authorization: Bearer NEW_ACCESS_TOKEN"

The HeyGen API endpoints support both authentication methods:

For OAuth Access Tokens:
- Use the Authorization header with the Bearer scheme.
- Format: Authorization: Bearer YOUR_ACCESS_TOKEN
- This is the method enabled by OAuth integration.
For API Tokens:
- Use the X-API-KEY header.
- Format: X-API-KEY: YOUR_API_TOKEN
- This is the existing method.

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:

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"

{
  "token_type": "Bearer",
  "access_token": "YyzWfeiqmklLsvzNsallQgUgfKHaNSnpv60BNgLGsC",
  "expires_in": 864000,
  "refresh_token": "dfU22fh6iD4aCkpy9GI32ulJXVe5eC8u4rt4SXedJHHich6L"
}

Get User's Account Information

After successfully authenticating with HeyGen, you can retrieve detailed account information using the following endpoint:

curl -X GET https://api2.heygen.com/v1/pacific/account.get \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

{
  "code": 100,
  "data": {
    "experiments": {
      "asset_face_swap": { "pass": false },
      "checkout_ui": { "pass": false },
      "consent_validation": { "group": "A", "pass": true },
      "create_button": { "pass": false },
      "dirty_word_block_level": { "pass": false },
      "exact_draft": { "pass": false },
      "instant_paid": { "group": "test", "pass": true },
      "notification": { "group": "A", "pass": true },
      "old_avatar": { "group": "A", "pass": true },
      "onboarding": { "pass": false },
      "onboarding2_bak": { "pass": false },
      "paywall_ui": { "pass": false },
      "studio_v3": { "pass": false }
    },
    "features": {
      "business_vt": true,
      "instant_avatar_upload": true,
      "new_stripe": true,
      "paid_voice": true,
      "vt_instruction": true
    },
    "space_info": {
      "owner_username": "<owner_username>",
      "permission_list": [
        "permission.draft.write",
        "permission.api.all",
        "permission.fe.payment",
        "permission.third_party_voice.all",
        "permission.fe.api_access",
        "permission.fe.permanent_content_deletion",
        "permission.role.write",
        "permission.asset.write",
        "permission.video.write",
        "permission.fe.content_access",
        "permission.payment.all",
        "permission.fe.credit_consumption"
      ],
      "role_list": [{ "id": "role_id.super_admin", "name": "Super Admin" }],
      "user_plan_v2": {
        "amount": 0.0,
        "api_access": true,
        "available_quota": {
          "regular": 300,
          "streaming_avatar_instance_quota": 1
        },
        "available_quota_v2": {
          "regular": { "amount": 300, "quota_type": "regular" },
          "streaming_avatar_instance_quota": {
            "amount": 1,
            "quota_type": "regular"
          }
        },
        "cancel_at_period_end": false,
        "created_ts": 1724491643,
        "downgrade_at_period_end": false,
        "downgrade_price_id": null,
        "downgrade_ts": null,
        "expired_ts": 1756027643,
        "is_gift": true,
        "is_paid": true,
        "is_unlimited": false,
        "left_days": 349,
        "pause_at_period_end": false,
        "period": "month",
        "price_id": "<price_id>",
        "remain_quota": 300,
        "remain_video": null,
        "resumes_at": 0,
        "self_serve_enterprise": false,
        "streaming_avatar_monthly_subscription_id": "",
        "streaming_avatar_subscription_id": "",
        "streaming_avatar_subscription_renew_ts": null,
        "streaming_avtar_monthly_subscription_renew_ts": null,
        "subscription_start_ts": "Sat, 24 Aug 2024 09:27:23 GMT",
        "subscription_type": "normal",
        "tier": "enterprise",
        "tier_id": "<tier_id>",
        "total_quota_in_min": 0,
        "total_quota_in_second": 0
      }
    },
    "user": {
      "ack_agreement": true,
      "asset_upload_limit": {
        "audio": 104857600,
        "image": 209715200,
        "video": 209715200
      },
      "disable_survey": true,
      "email": "<email>",
      "enable_payment": true,
      "has_api_access": true,
      "has_paid": true,
      "instant_avatar_access": true,
      "instant_avatar_slots": 5,
      "internal": false,
      "is_set_password": true,
      "is_subscription_active": true,
      "mfa": false,
      "phone": "",
      "pv_footage_duration_limit": null,
      "referral_quota": {
        "remaining_in_minutes": 0,
        "remaining_in_seconds": 0,
        "total_in_minutes": 0,
        "total_in_seconds": 0
      },
      "registration_ts": 1696430049,
      "survey": {
        "company_size": ["Only me"],
        "hear_from": ["TikTok"],
        "industry": ["Software, Online Service"],
        "role": ["Other:"],
        "video_content": ["Entertainment"]
      },
      "testing_group": "B",
      "third_party": {
        "facebook": { "is_bind": false, "name": null },
        "google": { "is_bind": true, "name": "<full-name>" },
        "rewardful": ""
      },
      "totp_created_ts": null,
      "user_hash": "<user_hash>",
      "user_id": "<user_id>",
      "username": "<username>",
      "usertype": "<usertype>",
      "video_duration_limit": 3600.0,
      "video_translate_duration_limit": 3600.0,
      "video_translate_filesize_limit": 5368709120
    },
    "user_plan_v2": {
      "amount": 0.0,
      "api_access": true,
      "available_quota": {
        "regular": 300,
        "streaming_avatar_instance_quota": 1
      },
      "available_quota_v2": {
        "regular": { "amount": 300, "quota_type": "regular" },
        "streaming_avatar_instance_quota": {
          "amount": 1,
          "quota_type": "regular"
        }
      },
      "cancel_at_period_end": false,
      "created_ts": 1724491643,
      "downgrade_at_period_end": false,
      "downgrade_price_id": null,
      "downgrade_ts": null,
      "expired_ts": 1756027643,
      "is_gift": true,
      "is_paid": true,
      "is_unlimited": false,
      "left_days": 349,
      "pause_at_period_end": false,
      "period": "month",
      "price_id": "<price_id>",
      "remain_quota": 300,
      "remain_video": null,
      "resumes_at": 0,
      "self_serve_enterprise": false,
      "streaming_avatar_monthly_subscription_id": "",
      "streaming_avatar_subscription_id": "",
      "streaming_avatar_subscription_renew_ts": null,
      "streaming_avtar_monthly_subscription_renew_ts": null,
      "subscription_start_ts": "Sat, 24 Aug 2024 09:27:23 GMT",
      "subscription_type": "normal",
      "tier": "enterprise",
      "tier_id": "<tier_id>",
      "total_quota_in_min": 0,
      "total_quota_in_second": 0
    }
  },
  "message": "Success"
}

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

The response includes detailed information about the user's account, experiments, features, and subscription plan.

Experiments: A list of feature experiments and their status for the user.
Features: Enabled features for the user's account.
Space Info: Information about the user's workspace, including permissions and roles.
User: Basic user information, including email, registration date, and subscription status.
User Plan: Detailed information about the user's subscription plan, including quotas, tier, and expiration.

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.

Conclusion

This guide provides a comprehensive approach to integrating HeyGen's API using OAuth 2.0 with the Authorization Code Flow and PKCE. By following these steps and best practices, you can securely authenticate users and access HeyGen's API on their behalf.