Skip to main content
Docs

Platform Integrations Overview

Platform integrations allow you to connect streaming platform accounts (Twitch, YouTube, Kick, Trovo) to Heimdall. This enables features like chat bots, channel management, and real-time event tracking.

Account Types​

There are two types of integrations:

TypeLimitPurpose
ChannelONE per platformMain streamer account - broadcasts, channel points, subscriptions
BotMULTIPLE per platformChat bots - messages, moderation (each with unique identifier)

Channel Integration​

The channel integration connects your main streamer/broadcaster account. This is used for:

  • Reading channel information
  • Managing channel points
  • Accessing subscription data
  • Receiving channel events (raids, follows, etc.)

You can only have one channel integration per platform.

Bot Integration​

Bot integrations connect accounts that will be used for chat interaction and moderation. You can connect multiple bot accounts per platform, each identified by a unique bot_identifier.

Bot integrations are used for:

  • Sending chat messages
  • Moderation actions (ban, timeout, etc.)
  • Responding to commands
  • Automated chat features

OAuth Security​

All platform integrations use OAuth 2.0 (or OAuth 2.1 with PKCE for Kick) for secure authorization:

  • No password storage - Heimdall never sees your platform password
  • Encrypted tokens - OAuth tokens are encrypted with AES-256-GCM at rest
  • Automatic refresh - Tokens are automatically refreshed before expiry
  • Scope-limited - Only request necessary permissions
  • Revocable - Disconnect anytime from platform settings or Heimdall

Supported Platforms​

PlatformOAuth VersionChannelBot
TwitchOAuth 2.0YesYes
YouTubeOAuth 2.0YesYes
KickOAuth 2.1 (PKCE)YesYes
TrovoOAuth 2.0YesYes

Managing Integrations​

Connecting an Integration​

  1. Navigate to Admin > Integrations in the dashboard
  2. Select the platform you want to connect
  3. Choose the integration type (Channel or Bot)
  4. For bot accounts, enter a unique bot identifier
  5. Click "Connect" to start the OAuth flow
  6. Authorize the requested permissions on the platform
  7. You'll be redirected back to Heimdall

Disconnecting an Integration​

  1. Navigate to Admin > Integrations
  2. Find the integration you want to remove
  3. Click "Disconnect"
  4. Confirm the disconnection

Disconnecting revokes Heimdall's access. You may also want to revoke access from the platform's settings:

  • Twitch: Settings > Security and Privacy > Connections
  • YouTube: Google Account > Security > Third-party apps
  • Kick: Settings > Connections
  • Trovo: Settings > Authorized Apps

Reconnecting an Integration​

If scopes change or you need to re-authorize with updated permissions:

  1. Navigate to Admin > Integrations
  2. Find the integration you want to reconnect
  3. Click "Reconnect"
  4. Authorize the updated permissions on the platform
  5. You'll be redirected back to Heimdall with the updated scopes

Reconnecting preserves your integration's settings and history while updating the OAuth tokens with new scopes. This is useful when:

  • New features require additional scopes
  • Platform API changes require new permissions
  • You previously denied a scope that is now needed

Refreshing Tokens​

Tokens are automatically refreshed before they expire. If you encounter issues:

  1. Navigate to Admin > Integrations
  2. Find the integration with the error
  3. Click "Refresh Token"

If refresh fails, you may need to disconnect and reconnect the integration.

API Access​

GraphQL​

# Get all integrations grouped by platform
query {
  allIntegrations {
    platformId
    platformSlug
    platformName
    channel {
      id
      platformUsername
      isActive
    }
    bots {
      id
      botIdentifier
      platformUsername
      isActive
    }
  }
}

# Get integrations for a specific platform
query {
  platformIntegrations(platform: "twitch") {
    id
    platformId
    integrationType
    botIdentifier
    platformUsername
    isActive
  }
}

# Get a specific integration
query {
  integration(id: "int_xxx") {
    id
    platformId
    integrationType
    platformUsername
    scopes
    isActive
  }
}

# Get available platforms
query {
  integrationPlatforms {
    slug
    platformId
    name
    isConfigured
  }
}

# Get available scopes for all platforms
query {
  allIntegrationScopes {
    platform
    channelScopes {
      scope
      description
      required
    }
    botScopes {
      scope
      description
      required
    }
  }
}

# Connect a channel integration (initiates OAuth flow)
mutation {
  connectIntegration(input: {
    platform: "twitch"
    integrationType: CHANNEL
  }) {
    authorizationUrl
    state
  }
}

# Connect a bot integration
mutation {
  connectIntegration(input: {
    platform: "twitch"
    integrationType: BOT
    botIdentifier: "mybot"
  }) {
    authorizationUrl
    state
  }
}

# Reconnect an existing integration (re-authorize with updated scopes)
mutation {
  connectIntegration(input: {
    platform: "twitch"
    integrationType: CHANNEL
    reconnect: true
  }) {
    authorizationUrl
    state
  }
}

# Disconnect an integration
mutation {
  disconnectIntegration(id: "int_xxx") {
    success
    error
  }
}

# Refresh an integration's token
mutation {
  refreshIntegrationToken(id: "int_xxx") {
    id
    isActive
  }
}

# Update Twitch bot status (badge and verified status)
mutation {
  updateTwitchBotStatus(input: {
    id: "int_xxx"
    hasVerifiedBotBadge: true
    isVerifiedBot: false
  }) {
    id
    hasVerifiedBotBadge
    isVerifiedBot
  }
}

REST API​

# List all integrations (grouped by platform)
GET /v1/integrations

# List integrations for a specific platform
GET /v1/integrations/platform/{slug}

# Get integration by ID
GET /v1/integrations/{id}

# Get available platforms
GET /v1/integrations/platforms

# Get available scopes for a platform
GET /v1/integrations/platform/{slug}/scopes

# Initiate OAuth flow
POST /v1/integrations/platform/{slug}/connect
Content-Type: application/json
{
  "integration_type": "bot",
  "bot_identifier": "mybot",
  "scopes": ["chat:read", "chat:write"]  // optional
}

# Reconnect an existing integration (re-authorize with updated scopes)
POST /v1/integrations/platform/{slug}/connect
Content-Type: application/json
{
  "integration_type": "channel",
  "reconnect": true
}

# Refresh token
POST /v1/integrations/{id}/refresh

# Disconnect
DELETE /v1/integrations/{id}

# Update Twitch bot status
PATCH /v1/integrations/{id}/twitch-status
Content-Type: application/json
{
  "has_verified_bot_badge": true,
  "is_verified_bot": false
}

# OAuth callback (called by platform after authorization)
GET /v1/integrations/callback/{platform}?code=xxx&state=xxx
URL Structure
  • Platform-specific routes use /platform/{slug} (e.g., /platform/twitch)
  • Integration ID routes use /{id} directly (IDs start with int_)
  • This avoids ambiguity between platform slugs and integration IDs

Audit Logging​

All integration actions are logged for security:

  • integration.connected - Integration successfully connected via OAuth
  • integration.disconnected - Integration disconnected by user
  • integration.token_refreshed - Token automatically or manually refreshed
  • integration.token_error - Token refresh failed
  • integration.status_updated - Integration status changed (e.g., Twitch bot badge)

View integration audit events at Admin > Audit Logs.

Internal Token API​

Future Feature

The internal token API for bots and services to request decrypted tokens is planned but not yet implemented.

When available, bots will be able to request tokens via:

POST /internal/integrations/{id}/token
X-Internal-Secret: <internal_service_key>

Configure the internal service key in your config:

[integrations]
internal_service_key = "your-secret-key"

Or via environment variable: INTERNAL_SERVICE_KEY

Next Steps​