Connection and Credential Aliases in ServiceNow: The Right Way to Store Integration Credentials

// Reference a named REST Message that uses a Connection Alias
var rm = new sn_ws.RESTMessageV2('Jira Integration', 'Create Issue');
// Credentials and base URL come from the Connection Alias configured
// on the named REST Message record — not hardcoded here
rm.setStringParameterNoEscape('summary', current.getValue('short_description'));
rm.setStringParameterNoEscape('project', 'OPS');
var response = rm.execute();

// In Flow Designer REST action step:
// Connection: [Select your Connection Alias]
// HTTP Method: POST
// Path: /rest/api/2/issue
// Body: JSON payload using data pills
// Credentials are injected automatically from the Connection Alias

// WRONG — credentials in code
var rm = new sn_ws.RESTMessageV2();
rm.setRequestHeader('Authorization', 'Bearer sk-abc123hardcoded');

// RIGHT — credential alias
var rm = new sn_ws.RESTMessageV2('My API', 'Get Data');
// Credentials come from the Connection Alias on the named REST Message

Credential types and when to use each

ServiceNow supports several credential types in the Credential record. Basic Auth stores a username and password — appropriate for development and simple internal APIs. API Key stores a single token passed as a header — common for SaaS APIs that use bearer token authentication without OAuth. OAuth 2.0 stores client ID and secret and handles token exchange and refresh automatically — use for any production integration that supports OAuth. Mutual TLS stores a client certificate — used for highly secure integrations where certificate-based authentication is required. Match the credential type to what the external system actually requires; do not use a more complex credential type than necessary.

Multi-instance credential management

In multi-instance environments (development, test, production), each instance typically needs its own credentials for external systems — development connects to staging APIs, production connects to production APIs. Use the same Connection Alias name across instances but configure different Credential records on each instance. The integration scripts reference the alias name, not the credential directly — so promoting a Update Set that contains the Connection Alias configuration does not overwrite the instance-specific credential. This is the correct pattern for managing environment-specific credentials without manual script changes during deployment.

Related: RESTMessageV2 · OAuth 2.0 · IntegrationHub spokes · MID Server

The Three Layers: Connection, Credential, and Alias

Understanding how these three components relate to each other prevents the configuration confusion that most people encounter when setting up integrations for the first time. A Credential record stores the actual secret — a username and password, an API key, or an OAuth token. A Connection record stores the non-secret connectivity details — the base URL, timeout settings, and any default headers. A Connection and Credential Alias ties these together under a named identifier that your integration scripts reference. The alias is what you put in your RESTMessageV2 or IntegrationHub spoke configuration — it abstracts the underlying credentials so that the same script works across dev, test, and production instances simply by swapping the alias target, without any code change.

Credential Types and When to Use Each

ServiceNow supports several credential types: Basic Auth (username + password), API Key (a single token sent as a header), OAuth 2.0 (with token refresh), Certificate-based, and SSH. Basic Auth and API Key are the simplest to configure and cover the majority of REST integrations. OAuth 2.0 is required when the target system uses token-based authentication with expiry — ServiceNow handles the token refresh cycle automatically once the OAuth profile is configured. Certificate-based credentials are used for mutual TLS integrations where the target server requires a client certificate, common in banking and healthcare integrations. SSH credentials are specific to Discovery and scripted SSH connections to Linux hosts via the MID Server.

Cross-Environment Credential Management

The alias pattern solves a significant operational problem in multi-environment ServiceNow setups. In a typical dev → test → production pipeline, each environment connects to different endpoints: development might connect to a sandbox Salesforce org, test to a Salesforce staging environment, and production to the live Salesforce instance. With aliases, the alias name (e.g., salesforce_crm) stays constant in your integration code across all environments. Only the underlying Credential and Connection records differ per environment — and those are preserved through clone preservers so they are not overwritten when production is cloned to lower environments. This separation eliminates an entire class of post-clone credential reconfiguration work.

Governance and Rotation

Centralising credentials in the Credentials module creates a governance foundation that scattered, hardcoded credentials cannot provide. You can audit every place a given credential is used by looking at what Connections reference it, and rotate the credential in one place knowing all integrations using that alias will automatically pick up the new value. For organisations subject to SOC 2 or PCI-DSS requirements, this auditability is essential — you need to demonstrate that credentials are not embedded in scripts and that rotation is systematic rather than manual. The Update Sets process for credential records requires care: credential records should generally be managed through preservers and environment-specific configuration rather than transported in Update Sets, which would overwrite target environment credentials with source environment values.

Troubleshooting Alias Resolution Failures

When an integration fails with a credentials error, the diagnostic path starts with verifying alias configuration. Check that the alias name in the integration script matches the alias record name exactly (case-sensitive). Verify that the Credential attached to the alias has not expired — OAuth tokens have expiry dates, and API keys are sometimes rotated by external systems without ServiceNow being updated. Check that the Connection record's base URL is correct for the current environment. For integrations using the MID Server, verify that the MID Server has network access to the target endpoint — a valid credential against an unreachable URL produces timeout errors that can look like authentication failures in logs. The debugging guide covers log analysis patterns for integration failures.

Alias Naming Conventions

Consistent alias naming across your instance makes integration code readable and maintenance straightforward. A good convention uses a format like system_environment_purpose: salesforce_prod_crm, slack_prod_notifications, workday_prod_hr. This naming makes it immediately clear which external system the alias connects to, which environment it targets, and what it is used for. When an alias name follows a consistent pattern, the integration code itself serves as documentation — a developer reading getConnection('salesforce_prod_crm') understands the target without needing to look up the alias record. Document all aliases in a central registry (a custom table or a SharePoint document) that includes the external system owner and the credential rotation schedule, enabling proactive credential management rather than reactive updates when credentials expire.

OAuth Token Lifecycle Management

OAuth 2.0 credentials in ServiceNow automatically refresh access tokens when they expire, but this requires the stored refresh token to be valid. Refresh tokens have longer expiry windows than access tokens (often 30-90 days) and can be invalidated by the target system's security policies (password resets, security policy changes, manual token revocation). When an integration fails with an authentication error after working correctly for weeks or months, an expired or invalidated refresh token is a common cause. The fix is to re-authenticate the OAuth profile by triggering the authorization flow again from the OAuth Provider record. For critical integrations, configure a monitoring alert that detects repeated 401 errors from a specific target system and notifies the integration owner — catching token invalidation within minutes of occurrence rather than discovering it through user-reported integration failures.