Managed Users and Embed Integrations

This guide explains how to use the Klap API v2 to create a user, generate an access token, and load the embed player. This workflow allows you to programmatically create users and provide them with authenticated access to specific projects via an embeddable player.

Prerequisites

• API Key: You need a valid API Key.
• Base URL: https://api.klap.app/v2 (or http://localhost:8080/v2 for local development).

Workflow

1. Create a User

First, create a “ghost” user associated with your organization. This user will have limited permissions defined by your organization’s settings.

Endpoint: POST /users

Request:

curl -X POST "https://api.klap.app/v2/users" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "id": "a8391290-66cc-47fc-9dff-c52bb8a8e3fc",
  "email": "user_slug@org_id.com",
  "organizationId": "your_org_id",
  "isGuest": true,
  ...
}

2. Create Content (Tasks, Exports)

When creating resources like Tasks (e.g., video-to-shorts) or Exports that should belong to this specific user, you must include the X-On-Behalf-Of header with the user’s ID.

Header: X-On-Behalf-Of: {user_id}

Example: Create a Video-to-Shorts Task

Endpoint: POST /tasks/video-to-shorts

Request:

curl -X POST "https://api.klap.app/v2/tasks/video-to-shorts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-On-Behalf-Of: a8391290-66cc-47fc-9dff-c52bb8a8e3fc" \
  -d '{
    "source_video_url": "https://www.youtube.com/watch?v=s2bVToRdY6A",
    "language": "en"
  }'

Response:

The response will contain a output_id (project ID) which you can use in the embed player.

{
  "id": "task_id...",
  "status": "processing",
  "output_id": "project_id...",
  ...
}

3. Generate an Access Token

Next, generate an access token for the user you just created. This token is used to authenticate the user in the embed player without requiring a password.

Endpoint: POST /users/{user_id}/tokens

Request:

Replace {user_id} with the id from the previous step.

curl -X POST "https://api.klap.app/v2/users/a8391290-66cc-47fc-9dff-c52bb8a8e3fc/tokens" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "external_access_token": "eyJh... (long JWT or token string)"
}

4. Load the Embed Player

Finally, construct the URL for the embed player. The player authenticates using the external_access_token passed in the URL hash fragment.

URL Format:

https://app.klap.app/embed/{project_id}#external_access_token={token}

• {project_id}: The ID of the project or media you want to display (e.g., tnX8jxsCNpvn).
• {token}: The external_access_token you generated in Step 2.

Example:

https://app.klap.app/embed/tnX8jxsCNpvn#external_access_token=eyJh...

Note: If you are running locally, the URL might be http://localhost:3000/embed/{project_id}#external_access_token={token}.