Authentication API

auth := helix.NewAuthClient(helix.AuthConfig{
    ClientID:     "your-client-id",
    ClientSecret: "your-client-secret",
    RedirectURI:  "http://localhost:3000/callback",
    Scopes:       []string{helix.ScopeChatRead, helix.ScopeChatEdit},
    State:        "random-state-string",
    ForceVerify:  false,
})

authURL, err := auth.GetCodeAuthURL()
if err != nil {
    log.Fatal(err)
}
fmt.Println("Visit:", authURL)
// Redirect user to authURL

// After user is redirected back with ?code=xxx
token, err := auth.ExchangeCode(ctx, "authorization-code-from-callback")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Access Token: %s\n", token.AccessToken)
fmt.Printf("Refresh Token: %s\n", token.RefreshToken)
fmt.Printf("Expires In: %d seconds\n", token.ExpiresIn)

authURL, err := auth.GetImplicitAuthURL()
if err != nil {
    log.Fatal(err)
}
// Token will be in URL fragment: #access_token=xxx&token_type=bearer

token, err := auth.GetAppAccessToken(ctx)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("App Access Token: %s\n", token.AccessToken)

deviceCode, err := auth.GetDeviceCode(ctx)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Go to: %s\n", deviceCode.VerificationURI)
fmt.Printf("Enter code: %s\n", deviceCode.UserCode)

token, err := auth.WaitForDeviceToken(ctx, deviceCode)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Access Token: %s\n", token.AccessToken)

token, err := auth.PollDeviceToken(ctx, deviceCode.DeviceCode)
if err == helix.ErrAuthorizationPending {
    // User hasn't authorized yet, wait and try again
}

validation, err := auth.ValidateToken(ctx, "access-token")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("User ID: %s\n", validation.UserID)
fmt.Printf("Login: %s\n", validation.Login)
fmt.Printf("Scopes: %v\n", validation.Scopes)
fmt.Printf("Expires In: %d seconds\n", validation.ExpiresIn)

validation, err := auth.ValidateCurrentToken(ctx)

newToken, err := auth.RefreshToken(ctx, "refresh-token")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("New Access Token: %s\n", newToken.AccessToken)

newToken, err := auth.RefreshCurrentToken(ctx)

err := auth.RevokeToken(ctx, "access-token")
if err != nil {
    log.Fatal(err)
}
fmt.Println("Token revoked successfully")

err := auth.RevokeCurrentToken(ctx)

cancel := auth.AutoRefresh(ctx)
defer cancel() // Stop auto-refresh when done

// Token will be automatically refreshed 5 minutes before expiry

if token.IsExpired() {
    // Refresh the token
}

if token.Valid() {
    // Use the token
}

// Store a token
auth.SetToken(&helix.Token{
    AccessToken:  "your-token",
    RefreshToken: "your-refresh-token",
    ExpiresIn:    14400,
})

// Retrieve the stored token
token := auth.GetToken()

// Each request uses a different user's token
ctx := helix.WithToken(context.Background(), &helix.Token{
    AccessToken: "user-specific-token",
})
followers, err := client.GetChannelFollowers(ctx, &helix.GetChannelFollowersParams{
    BroadcasterID: "12345",
})

config, err := auth.GetOpenIDConfiguration(ctx)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Issuer: %s\n", config.Issuer)
fmt.Printf("Token Endpoint: %s\n", config.TokenEndpoint)

authURL, err := auth.GetOIDCAuthorizationURL(
    helix.ResponseTypeCodeIDToken,
    "random-nonce",
    nil, // Optional claims parameter
)

oidcToken, err := auth.ExchangeCodeForOIDCToken(ctx, "authorization-code")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Access Token: %s\n", oidcToken.AccessToken)
fmt.Printf("ID Token: %s\n", oidcToken.IDToken)

userInfo, err := auth.GetOIDCUserInfo(ctx, "access-token")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("User ID: %s\n", userInfo.Sub)
fmt.Printf("Username: %s\n", userInfo.PreferredUsername)
fmt.Printf("Email: %s\n", userInfo.Email)

userInfo, err := auth.GetCurrentOIDCUserInfo(ctx)

jwks, err := auth.GetJWKS(ctx)
if err != nil {
    log.Fatal(err)
}
key := jwks.GetKeyByID("1")
if key != nil {
    rsaKey, err := key.RSAPublicKey()
    // Use rsaKey to verify ID token signatures
}

claims, err := helix.ParseIDToken(oidcToken.IDToken)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("User ID: %s\n", claims.Sub)
fmt.Printf("Username: %s\n", claims.PreferredUsername)
fmt.Printf("Email: %s\n", claims.Email)

err := auth.ValidateIDTokenClaims(claims, "random-nonce")
if err != nil {
    log.Fatal("Invalid ID token:", err)
}

// Analytics
helix.ScopeAnalyticsReadExtensions  // "analytics:read:extensions"
helix.ScopeAnalyticsReadGames       // "analytics:read:games"

// Bits
helix.ScopeBitsRead                 // "bits:read"

// Channel
helix.ScopeChannelBot               // "channel:bot"
helix.ScopeChannelEditCommercial    // "channel:edit:commercial"
helix.ScopeChannelManageAds         // "channel:manage:ads"
helix.ScopeChannelManageBroadcast   // "channel:manage:broadcast"
helix.ScopeChannelManageModerators  // "channel:manage:moderators"
helix.ScopeChannelManagePolls       // "channel:manage:polls"
helix.ScopeChannelManagePredictions // "channel:manage:predictions"
helix.ScopeChannelManageRaids       // "channel:manage:raids"
helix.ScopeChannelManageRedemptions // "channel:manage:redemptions"
helix.ScopeChannelManageSchedule    // "channel:manage:schedule"
helix.ScopeChannelManageVideos      // "channel:manage:videos"
helix.ScopeChannelManageVIPs        // "channel:manage:vips"
helix.ScopeChannelReadSubscriptions // "channel:read:subscriptions"
// ... and many more

// Chat
helix.ScopeChatRead                 // "chat:read"
helix.ScopeChatEdit                 // "chat:edit"

// Moderation
helix.ScopeModerationRead           // "moderation:read"
helix.ScopeModeratorManageBannedUsers    // "moderator:manage:banned_users"
helix.ScopeModeratorManageChatMessages   // "moderator:manage:chat_messages"
// ... and many more

// User
helix.ScopeUserReadEmail            // "user:read:email"
helix.ScopeUserManageWhispers       // "user:manage:whispers"
helix.ScopeUserWriteChat            // "user:write:chat"
// ... and many more

// Chat bot scopes
auth := helix.NewAuthClient(helix.AuthConfig{
    Scopes: helix.CommonScopes.Chat,
    // Includes: chat:read, chat:edit, user:write:chat, user:read:chat
})

// Moderation scopes
auth := helix.NewAuthClient(helix.AuthConfig{
    Scopes: helix.CommonScopes.Moderation,
    // Includes: moderation:read, moderator:manage:banned_users, etc.
})

// Bot scopes (chat + bot permissions)
auth := helix.NewAuthClient(helix.AuthConfig{
    Scopes: helix.CommonScopes.Bot,
    // Includes: chat:read, chat:edit, channel:bot, user:bot, etc.
})

// Broadcaster scopes (comprehensive channel management)
auth := helix.NewAuthClient(helix.AuthConfig{
    Scopes: helix.CommonScopes.Broadcaster,
    // Includes: channel management, moderation, polls, predictions, etc.
})

// Analytics scopes
auth := helix.NewAuthClient(helix.AuthConfig{
    Scopes: helix.CommonScopes.Analytics,
    // Includes: analytics:read:extensions, analytics:read:games
})

var (
    helix.ErrInvalidToken         // Invalid access token
    helix.ErrTokenExpired         // Token has expired
    helix.ErrAuthorizationPending // Device code flow: user hasn't authorized yet
    helix.ErrInvalidDeviceCode    // Invalid device code
    helix.ErrInvalidRefreshToken  // Invalid refresh token
    helix.ErrMissingClientID      // Client ID is required
    helix.ErrMissingClientSecret  // Client secret is required
    helix.ErrMissingRedirectURI   // Redirect URI is required
    helix.ErrMissingCode          // Authorization code is required
)

token, err := auth.RefreshToken(ctx, refreshToken)
if err != nil {
    switch err {
    case helix.ErrInvalidRefreshToken:
        // Refresh token is invalid, need to re-authenticate
    case helix.ErrMissingClientSecret:
        // Configuration error
    default:
        // Other error
    }
}