Implementation:Helicone Helicone UseProvider

Knowledge Sources	Helicone
Domains	Provider Management, API Key Vault
Last Updated	2026-02-14 06:32 GMT

Overview

Unified React hook for managing LLM provider API keys through the Jawn backend, supporting CRUD operations with TanStack Query cache management.

Description

The useProvider hook provides a complete interface for managing LLM provider keys within an organization. It uses TanStack Query for data fetching and cache invalidation, and communicates with the Jawn backend via typed API client calls. The hook supports:

• Fetching all provider keys for the current organization via GET /v1/api-keys/provider-keys
• Creating new provider keys via POST /v1/api-keys/provider-key with provider name, key, optional secret key, display name, config, and BYOK enablement
• Updating existing keys via PATCH /v1/api-keys/provider-key/{providerKeyId} with conditional field inclusion
• Deleting keys via DELETE /v1/api-keys/provider-key/{providerKeyId}
• Viewing decrypted keys via GET /v1/api-keys/provider-key/{providerKeyId} for temporary display

When a specific Provider is passed, the hook also computes an existingKey by filtering provider keys matching that provider's ID. All mutations trigger automatic query cache invalidation for the provider keys query.

Usage

Use this hook in provider key management UIs, vault pages, and any component that needs to add, edit, delete, or view provider API keys. It can operate in global mode (all keys) or provider-specific mode (with filtered existing key lookup).

Code Reference

Source Location

• Repository: Helicone
• File: web/hooks/useProvider.ts

Signature

interface UseProviderParams {
  provider?: Provider;
}

export const useProvider: (params?: UseProviderParams) => {
  providerKeys: ProviderKey[];
  isLoadingKeys: boolean;
  existingKey: ProviderKey | undefined;
  addProviderKey: UseMutationResult;
  updateProviderKey: UseMutationResult;
  deleteProviderKey: UseMutationResult;
  isSavingKey: boolean;
  isSavedKey: boolean;
  isDeletingKey: boolean;
  viewDecryptedProviderKey: (keyId: string) => Promise<{
    providerKey: string;
    providerSecretKey?: string | null;
  } | null>;
  refetchProviderKeys: () => void;
};

Import

import { useProvider } from "@/hooks/useProvider";

I/O Contract

Parameters

Parameter	Type	Required	Description
provider	Provider	No	When provided, enables provider-specific mode with existingKey lookup

Return Value

Property	Type	Description
providerKeys	ProviderKey[]	All provider keys for the current organization
isLoadingKeys	boolean	Always false (reserved for future loading state)
existingKey	undefined	The first non-deleted key matching the specified provider
addProviderKey	UseMutationResult	Mutation for creating a new provider key
updateProviderKey	UseMutationResult	Mutation for updating an existing provider key
deleteProviderKey	UseMutationResult	Mutation for soft-deleting a provider key
isSavingKey	boolean	Whether an add or update mutation is in progress
isSavedKey	boolean	Whether the last add or update mutation succeeded
isDeletingKey	boolean	Whether a delete mutation is in progress
viewDecryptedProviderKey	function	Async function to fetch the decrypted key value
refetchProviderKeys	function	Manually refetch the provider keys query

Add Provider Key Mutation Parameters

Field	Type	Required	Description
providerName	string	Yes	The LLM provider identifier
key	string	Yes	The API key value
secretKey	string	No	Optional secret key for providers that require it
providerKeyName	string	Yes	Display name for the key
config	Record<string, any>	No	Provider-specific configuration
byokEnabled	boolean	Yes	Whether the key is enabled for AI Gateway BYOK

Usage Examples

import { useProvider } from "@/hooks/useProvider";

function ProviderKeyManager() {
  const {
    providerKeys,
    addProviderKey,
    deleteProviderKey,
    viewDecryptedProviderKey,
  } = useProvider();

  const handleAdd = () => {
    addProviderKey.mutate({
      providerName: "openai",
      key: "sk-...",
      providerKeyName: "My OpenAI Key",
      byokEnabled: true,
    });
  };

  const handleView = async (keyId: string) => {
    const decrypted = await viewDecryptedProviderKey(keyId);
    if (decrypted) {
      console.log(decrypted.providerKey);
    }
  };

  return (
    <div>
      {providerKeys.map((key) => (
        <div key={key.id}>{key.provider_key_name}</div>
      ))}
    </div>
  );
}

Related Pages

• Principle:Helicone_Helicone_Provider_Key_Management
• Helicone_Helicone_Provider_Key_Types