Programmatic Credentials

ClassifAI supports programmatic credential management through a unified filter hook, allowing you to integrate external secret management services like Azure Key Vault or AWS Secrets Manager, or manage credentials via environment variables.

Overview

By default, ClassifAI stores API credentials in the WordPress database. The classifai_provider_credentials and classifai_provider_credentials_{$provider_id} filters allow you to override these credentials at runtime, enabling integration with external secret management systems where credentials should be fetched dynamically rather than stored in the database.

The Filter Hook

The primary hooks for credential filtering are classifai_provider_credentials and classifai_provider_credentials_{$provider_id}. These filters fire before every API request, allowing you to override credentials programmatically.

Filter Parameters

apply_filters(
    'classifai_provider_credentials',
    $credentials, // Array of credentials from database settings
    $provider_id, // Provider ID (e.g., 'azure_openai', 'openai_chatgpt')
    $feature_id, // Feature ID making the request (e.g., 'feature_title_generation')
    $feature_provider_settings // Feature-specific Provider settings
);

apply_filters(
    'classifai_provider_credentials_{$provider_id}',
    $credentials, // Array of credentials from database settings
    $feature_id, // Feature ID making the request (e.g., 'feature_title_generation')
    $feature_provider_settings // Feature-specific Provider settings
);

Return Value

The filter should return an array of credentials matching the Provider's expected format. The array keys vary by Provider:

• Azure Providers: api_key, endpoint_url, deployment (for OpenAI/Embeddings)
• OpenAI Providers: api_key
• Google AI Providers: api_key
• IBM Watson Providers: username, password, endpoint_url
• AWS Polly Providers: access_key_id, secret_access_key, aws_region
• ElevenLabs Providers: api_key
• xAI Grok Providers: api_key

Usage Examples

Azure Key Vault Integration

This example shows how to fetch credentials from Azure Key Vault for Azure OpenAI Providers:

add_filter( 'classifai_provider_credentials', function( $credentials, $provider_id, $feature_id ) {
    // Only override for Azure Providers
    if ( ! str_starts_with( $provider_id, 'azure_' ) ) {
        return $credentials;
    }

    // Initialize Azure Key Vault client (requires Azure SDK)
    $vault_client = new \Azure\KeyVault\SecretClient(
        'https://your-vault.vault.azure.net',
        new \Azure\Identity\DefaultAzureCredential()
    );

    // Fetch secrets from Key Vault
    $api_key = $vault_client->getSecret( "classifai-{$provider_id}-api-key" )->getValue();
    $endpoint = $vault_client->getSecret( "classifai-{$provider_id}-endpoint" )->getValue();

    return array_merge( $credentials, [
        'api_key'      => $api_key,
        'endpoint_url' => $endpoint,
        // Keep deployment from settings if not in vault
        'deployment'   => $credentials['deployment'] ?? '',
    ] );
}, 10, 3 );

Environment Variable Credentials

Use environment variables for credentials instead of storing them in the database:

add_filter( 'classifai_provider_credentials', function( $credentials, $provider_id, $feature_id ) {
    // Convert provider_id to environment variable format
    $env_key = strtoupper( str_replace( '-', '_', "CLASSIFAI_{$provider_id}_API_KEY" ) );

    if ( defined( $env_key ) ) {
        $credentials['api_key'] = constant( $env_key );
    }

    // Handle Azure Providers that need endpoint_url
    if ( str_starts_with( $provider_id, 'azure_' ) ) {
        $env_endpoint = strtoupper( str_replace( '-', '_', "CLASSIFAI_{$provider_id}_ENDPOINT" ) );
        if ( defined( $env_endpoint ) ) {
            $credentials['endpoint_url'] = constant( $env_endpoint );
        }
    }

    return $credentials;
}, 10, 3 );

Feature-Specific Credentials

Use different API keys for different Features:

add_filter( 'classifai_provider_credentials', function( $credentials, $provider_id, $feature_id ) {
    // Use premium API key for content generation
    if ( 'feature_content_generation' === $feature_id ) {
        $credentials['api_key'] = get_option( 'classifai_premium_api_key' );
    }

    // Use standard API key for other features
    return $credentials;
}, 10, 3 );

Provider-Specific Override

Override credentials for a specific Provider:

add_filter( 'classifai_provider_credentials', function( $credentials, $provider_id, $feature_id ) {
    // Only override for OpenAI ChatGPT
    if ( 'openai_chatgpt' === $provider_id ) {
        $credentials['api_key'] = get_option( 'custom_openai_key' );
    }

    return $credentials;
}, 10, 3 );

or

add_filter( 'classifai_provider_credentials_openai_chatgpt', function( $credentials, $feature_id ) {
    $credentials['api_key'] = get_option( 'custom_openai_key' );

    return $credentials;
}, 10, 2 );

Important Considerations

Caching

When using external secret management services, implement caching to avoid excessive API calls:

add_filter( 'classifai_provider_credentials', function( $credentials, $provider_id, $feature_id ) {
    $cache_key = "classifai_creds_{$provider_id}_{$feature_id}";
    $cached = get_transient( $cache_key );

    if ( false !== $cached ) {
        return $cached;
    }

    // Fetch from external service
    $vault_credentials = fetch_from_key_vault( $provider_id );

    // Merge with the original credentials
    $credentials = array_merge( $credentials, $vault_credentials );

    // Cache for 5 minutes
    set_transient( $cache_key, $credentials, 5 * MINUTE_IN_SECONDS );

    return $credentials;
}, 10, 3 );

Settings Page Authentication

The authentication check on the settings page also uses filtered credentials. This means your integration will be tested when users save settings, ensuring credentials are valid.

Security

Filtered credentials are never stored back to the database. They are only used for the current API request and discarded afterward.