What Are Named Credentials in Salesforce AI?

Every AI integration on Salesforce requires authentication credentials - API keys or tokens that grant access to AI compute resources. How you store these credentials determines your security posture, compliance eligibility, and operational risk.

The default approaches most teams consider - Custom Settings, Custom Metadata Types, or hardcoded Apex - share a fundamental flaw: credentials are stored in plain text and accessible to any code or administrator in the org. This creates multiple risk vectors:

• Credential extraction: Any Apex code with SOQL access can query and exfiltrate API keys
• Sandbox leakage: Production credentials automatically copy to sandboxes during refresh, exposing them to non-production environments
• Debug log exposure: Values can appear in debug logs when logging is enabled
• Metadata export: Credentials travel with change sets and deployment packages

For enterprises in regulated industries - financial services, healthcare, insurance - these risks translate to compliance violations. SOC 2, HIPAA, PCI-DSS, and FINRA all require strict controls over how authentication secrets are stored and accessed. GPTfy's security layer addresses this by building Named Credential support directly into the platform, with no workarounds required.

Salesforce offers multiple mechanisms for storing data. Not all are appropriate for AI credentials. Here is how the options compare for enterprise security:

Hardcoded in Apex

Risk Level: Critical. API keys embedded as string constants in Apex classes are visible to any developer with "View All Classes" permission. They persist in version control, appear in change sets, and can surface in debug logs. Salesforce explicitly warns against this pattern.

Verdict: Never acceptable for production. Represents a fundamental security violation.

Custom Labels

Risk Level: High. Designed for translatable UI text, not secrets. Values are not encrypted, visible to any administrator in Setup, and included in metadata deployments. Salesforce documentation explicitly states Custom Labels should only be used for non-sensitive text.

Verdict: Explicitly inappropriate for secrets.

Custom Settings

Risk Level: Moderate-to-High. Values are stored in queryable sObjects - any Apex code with SOQL access can retrieve them. While "protected" visibility hides data from subscribers in managed packages, within your org the data remains accessible through API queries. Production values propagate to sandboxes during refresh. Security researchers have documented Custom Settings as a common target for credential extraction attacks.

Verdict: Better than hardcoding but fundamentally insecure for AI credentials.

Custom Metadata Types

Risk Level: Moderate. Within managed packages with "protected" visibility, values are hidden from subscribing orgs. However, unprotected records are queryable by any code. Values travel with metadata deployments and can be extracted during org migrations. Salesforce security community consensus: Custom Metadata Types were designed for application configuration, not secrets.

Verdict: Acceptable only within managed packages with protected visibility. Not recommended for customer-managed AI credentials.

Named Credentials with External Credentials

Risk Level: Enterprise-grade. The only Salesforce-native mechanism providing encryption at rest, server-side credential injection (keys never appear in code or logs), permission-based access control, non-exportability (write-only), and sandbox isolation. Salesforce's official recommendation for all external service integrations.

Verdict: The only option meeting enterprise security requirements.

Salesforce's developer documentation is explicit about the correct approach for external service authentication:

"A named credential specifies the URL of a callout endpoint and its required authentication parameters in one definition. Salesforce manages all authentication for Apex callouts that specify a named credential as the callout endpoint so that your code doesn't have to."

Furthermore, Salesforce's Winter '23 release introduced the External Credentials framework and explicitly deprecated legacy approaches:

"We strongly recommend that you use this preferred credential instead of legacy named credentials. Legacy named credentials are deprecated and will be discontinued in a future release."

Salesforce Trailhead's "Securely Store Secrets" module specifically identifies Named Credentials as the recommended mechanism for authentication credentials, noting they provide "standard authentication implementation processes in a set of secure and manageable entities" where "credential passwords cannot be made visible in the UI, accessed through API, or made visible in debug logs."

The Salesforce security community - including researchers at NetSPI and Valence Security - has independently validated that Named Credentials represent the most secure approach. Their research documents that Custom Settings, Custom Metadata Types, and Custom Objects are frequently targeted for credential extraction, while Named Credentials' write-only architecture provides effective defense.

GPTfy's BYOK (Bring Your Own Key) architecture rests on a fundamental principle: your AI credentials never leave your Salesforce environment, and GPTfy never has access to them.

The Architecture Flow

1. You provision your AI service (Azure OpenAI, OpenAI, etc.) and obtain your API key directly from the provider
2. You configure Named Credentials in your Salesforce org - External Credential for authentication, Named Credential for endpoint binding
3. You reference the Named Credential in GPTfy's AI Model record by name only - GPTfy never sees the actual credential value
4. At runtime, Salesforce injects credentials server-side when GPTfy initiates the callout using the callout: prefix

GPTfy operates as a credential-agnostic orchestration layer. We know which Named Credential to use, but never what credentials it contains. Your API keys are encrypted at rest using Salesforce's platform encryption, injected at runtime by Salesforce's infrastructure, and never transmitted to GPTfy or any third party.

This architecture is what makes Bring Your Own Model viable for regulated industries. You retain the contractual relationship with your AI provider, GPTfy handles the orchestration, and Named Credentials ensure the authentication chain never exposes your keys.

Key Security Properties

• Namespace isolation: By specifying ccai (GPTfy's namespace) as the allowed callout namespace, you ensure only GPTfy's managed package code can use the credential
• Permission Set gating: Only users explicitly assigned the relevant Permission Set can trigger AI callouts
• Key rotation without code changes: Update the credential in Setup - no deployment, no GPTfy involvement, zero downtime. The audit trail captures every rotation event with timestamp and actor
• Complete audit trail: All credential access and modifications are tracked in Salesforce's Setup Audit Trail

External Credentials support multiple authentication protocols, each suited to different AI provider requirements. Understanding which protocol to use is essential for a successful integration. For teams configuring BYOM in GPTfy, the authentication protocol selection happens at the External Credential level - GPTfy itself remains protocol-agnostic.

OAuth 2.0 Client Credentials

The recommended protocol for most modern AI providers, including OpenAI, Azure OpenAI, and Anthropic. Client Credentials flow is a machine-to-machine protocol where your application authenticates directly with the AI provider using a client ID and secret - no user login required.

In Salesforce, configure an External Credential with Protocol set to "OAuth 2.0" and Flow Type set to "Client Credentials." The client ID and secret are stored encrypted in the External Credential; GPTfy references only the Named Credential endpoint.

OAuth 2.0 JWT Bearer

Used in enterprise integrations where the AI provider requires JWT-signed assertions for authentication - common in regulated environments with strict identity requirements. AWS Bedrock via Amazon Cognito and some Azure enterprise configurations use this pattern.

Salesforce generates and signs the JWT automatically using your configured private key, reducing the risk of key mishandling in application code. This protocol works best for teams with existing PKI infrastructure.

AWS Signature Version 4

Required for direct AWS Bedrock API access and other AWS service integrations. AWS SigV4 signs every request with your AWS access key and secret, providing request-level integrity verification.

When configured as an External Credential, Salesforce computes the SigV4 signature server-side. Your AWS credentials are never exposed in Apex code, HTTP headers visible in logs, or debug output - a critical requirement for AWS security compliance.

Custom (API Key / Bearer Token)

For AI providers that use simple API key or Bearer token authentication (a common pattern for self-hosted or on-premises models), the "Custom" protocol in External Credentials allows you to define custom HTTP headers carrying the credential.

The key is stored encrypted in Salesforce and injected into the Authorization header at runtime. This is the simplest configuration path for providers with non-standard authentication schemes.

Legacy Named Credentials (Deprecated)

Prior to Winter '23, Named Credentials combined endpoint and authentication into a single record, supporting Password, OAuth 2.0, and JWT protocols. While still functional, Salesforce has deprecated this approach and will discontinue it in a future release.

If you are operating on a legacy setup, migrate to External Credentials. GPTfy supports both, but recommends External Credentials for all new configurations.

Named Credentials are not just a convenience - they are a security control required by major compliance frameworks. GPTfy's security and compliance hub documents how Named Credentials map to each framework's specific controls.

SOC 2 Type II

Requires encryption of authentication data at rest and in transit, access controls, audit logging, and separation of duties between credential configuration and code development. Named Credentials satisfy all four requirements through native Salesforce functionality.

HIPAA

Healthcare organizations must ensure credentials accessing PHI-processing systems operate under strict access controls with full audit trails. Named Credentials' permission-based access and Setup Audit Trail integration satisfy these requirements. When combined with GPTfy's data masking, the result is a credential layer and a data layer both meeting HIPAA requirements. See how healthcare organizations use this combination for compliant AI workflows.

GDPR and Data Sovereignty

BYOK architecture ensures the customer - not GPTfy - maintains the contractual relationship with the AI provider. Data processing agreements, data residency commitments, and processor/controller relationships remain between you and your AI provider. GPTfy operates as a technical orchestrator, not a data processor. The privacy compliance demo walks through how this architecture satisfies GDPR Article 28 requirements.

Financial Services (FINRA, SEC, OCC)

Financial institutions benefit from non-exportable credential storage that prevents unauthorized extraction or replication. Combined with GPTfy's four-layer data masking, this creates a defense-in-depth approach to AI integration security that addresses FINRA Rule 4370, SEC Rule 17a-4, and OCC guidance on third-party AI risk.

The SPEC Security datasheet maps each Named Credential security property to the specific control numbers across SOC 2, HIPAA, PCI-DSS, and FINRA frameworks.

Related: Learn more about GPTfy's Zero-Trust Architecture and Data Masking for complete security coverage.

Agentic AI systems make autonomous API callouts - potentially hundreds per session, across multiple AI providers. Each callout requires secure, auditable authentication. Named Credentials provide the security architecture that lets agentic AI scale: encrypted credentials, server-side injection, Setup Audit Trail logging for every callout, and permission controls that determine which agents can access which AI providers.

For organizations adopting agentic AI at enterprise scale, this security infrastructure must be in place before trusting agents to operate autonomously. The authentication layer cannot be bolted on after deployment - it needs to be woven into every callout from the start.

GPTfy's BYOK architecture, built on Named Credentials, is designed to meet this requirement. Agents route to any configured AI provider through the same authenticated, logged, permission-gated mechanism - so every autonomous callout is as auditable as a human-triggered one. The security architecture demo shows this authentication flow end-to-end. Learn more about the full security posture in Zero-Trust Architecture.

Follow these patterns to maximize security and maintainability:

Separate Credentials by Environment

Create different Named Credentials for sandbox and production (e.g., "OpenAI Sandbox" vs "OpenAI Production"). This prevents accidental production API calls during testing and limits blast radius if a sandbox is compromised.

Use External Credentials for Production

In production orgs, always use External Credentials (the modern approach) rather than Legacy Named Credentials. External Credentials separate the authentication protocol from the credential values, enabling better secret rotation and access control.

Apply Principle of Least Privilege

Only grant External Credential access to Permission Sets that actually need AI capabilities. Do not give all users access to production AI endpoints - restrict to specific roles and integration users.

Monitor Setup Audit Trail

Regularly review changes to Named Credentials and External Credentials. Track who created, modified, or accessed credential configurations. Unexplained changes should trigger security review. GPTfy's audit trails and governance feature extends this visibility beyond credential changes to every AI callout - giving you a complete picture of AI activity in your org.

Rotate Credentials Quarterly

Establish a schedule for API key rotation. With External Credentials, rotation is a UI action - no code changes or deployment required. Document your rotation schedule for auditor review.

Document Your Credential Strategy

Maintain a runbook documenting which Named Credentials exist, which AI providers they connect to, which Permission Sets have access, and the rotation schedule. Your security auditor will request this documentation. The integration approaches guide covers how different Salesforce integration patterns affect credential strategy across multi-model deployments.