Embed Session API

The Embed Session API allows you to create authenticated embed sessions for boards, enabling users to access board content through embedded interfaces with customizable user information and metadata.

Endpoint

POST /api/embed/sessions

Authentication

This endpoint requires API Key authentication. Include your API key in the request headers:

Authorization: Bearer YOUR_API_KEY

Request Body

Response

Returns a JSON object containing the created session details:

Authorization Rules

Embed sessions can only be created for boards that meet one of these conditions:

1. The board has PUBLIC visibility
2. The board is owned by an organization where the API key owner is a member

Example Request

curl -X POST https://your-domain.com/api/embed/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "boardId": "board_123abc",
    "userId": "user_456def",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "avatarUrl": "https://example.com/avatars/johndoe.jpg",
    "plan": "pro",
    "metadata": {
      "source": "webapp",
      "accountType": "business",
      "customField": "value"
    },
    "expiresInSeconds": 604800
  }'

Example Response

{
  "session": {
    "id": "clx123abc456",
    "boardId": "board_123abc",
    "token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "userId": "user_456def",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "avatarUrl": "https://example.com/avatars/johndoe.jpg",
    "plan": "pro",
    "metadata": {
      "source": "webapp",
      "accountType": "business",
      "customField": "value"
    },
    "expiresAt": "2026-02-03T12:00:00.000Z",
    "createdAt": "2026-01-27T12:00:00.000Z"
  },
  "sessionToken": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "embedUrl": "https://your-domain.com/embed?token=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

Error Responses

401 Unauthorized

API key is missing or invalid.

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

403 Forbidden

Board is not accessible with the provided API key.

{
  "error": "Forbidden",
  "message": "Embed sessions can only be created for public boards or boards owned by your organization"
}

404 Not Found

Board with the specified ID does not exist.

{
  "error": "Not Found",
  "message": "Board not found"
}

400 Bad Request

Invalid request body or validation error.

{
  "error": "Bad Request",
  "message": "Invalid email format"
}

Usage Notes

Session Tokens

• Tokens are cryptographically secure random strings (32 characters)
• Each token is unique and cannot be reused
• Tokens are passed as query parameters in the embed URL

Expiration

• Default expiration is 30 days (2,592,000 seconds)
• Custom expiration can be set from 1 second to any positive integer value
• Expired sessions cannot be used to access embedded content
• Sessions with past expiration dates can be created but are immediately invalid

User Identification

• userId should be a unique identifier from your system
• The same userId can have multiple active sessions for different boards
• User information (firstName, lastName, avatarUrl) is used for display purposes in the embedded interface

Metadata

• Store any custom data as key-value pairs
• Useful for tracking session source, feature flags, or custom attributes
• Maximum nesting and size depends on your database configuration
• Empty objects {} are valid

Multiple Sessions

• Multiple sessions can be created for the same board
• Multiple sessions can be created for the same user across different boards
• Each session has a unique token and can have different expiration times

Embed URL Usage

The returned embedUrl can be used directly in an iframe or as a standalone link:

<iframe
  src="https://your-domain.com/embed?token=SESSION_TOKEN"
  width="100%"
  height="600"
  frameborder="0"
></iframe>

Best Practices

1. Security: Store API keys securely and never expose them in client-side code
2. Token Handling: Treat session tokens as sensitive credentials
3. Expiration: Set appropriate expiration times based on your use case
4. Validation: Always validate the response and handle errors appropriately
5. Metadata: Use metadata for tracking and analytics, but avoid storing sensitive information
6. Rate Limiting: Implement rate limiting on your side to prevent excessive session creation