ServiceNow Connection and Credential Alias Explained

What Connection and Credential Alias Is

A Connection is a ServiceNow record that defines how to connect to an external system: the host name, port, protocol and authentication method. A Credential Alias is a named reference to stored authentication information. Rather than storing passwords or API keys in integration logic, the integration references a Credential Alias by name. ServiceNow looks up the alias and retrieves the actual credentials securely. This approach separates system configuration from secrets, making integration code portable and credential management centralised.

When a developer creates an integration, they reference the connection and credential alias by name. If the connection host changes or credentials are rotated, only the Connection and Credential Alias records are updated. The integration code never changes. This reduces the risk that someone has to touch code to manage secrets, and it allows credential rotation without redeploying integration logic.

Where Connection and Credential Alias Live in the Platform

Connections are managed in the Integration Hub or MID Server configuration, depending on your integration approach. A Connection specifies the external system: host, port, protocol, connection type (basic auth, OAuth, certificate-based) and which Credential Alias to use for authentication. Credential Aliases are stored securely in the platform and encrypted. Multiple connections can reference the same credential alias, or each connection can have its own. When a flow runs and needs to authenticate, it retrieves the connection and credential, and ServiceNow decrypts the credential only when needed.

Credential Aliases are created in the Credential Management application, and access to create or edit them is restricted to administrators. This prevents developers or integration builders from accidentally viewing or modifying passwords. Only those with security credentials management role can update credentials.

A Worked Example: Integration to an External API

Your organisation needs to sync user data from an external HR system API. The integration runs nightly and pulls active employee records. First, create a Connection record specifying the HR system API host, protocol (HTTPS), and authentication method (OAuth). Create a Credential Alias called hr_system_oauth with the OAuth client ID and secret. The connection references this alias by name.

Next, create a flow that runs nightly. The flow references the Connection by name. When the flow starts, ServiceNow looks up the Connection, retrieves the associated Credential Alias, decrypts it and uses it to authenticate to the HR API. The flow pulls employee data and creates or updates user records in ServiceNow. If the HR system changes the API endpoint, only the Connection host is updated. If OAuth credentials are rotated, only the Credential Alias is changed. The flow logic never changes.

Security and Access Control

Storing credentials securely is critical. ServiceNow encrypts credential aliases when they are stored so even database administrators cannot see them in the database. Credentials are decrypted in memory only when needed for authentication. Access to credential management is restricted to administrators with the proper role. Audit logs track who created or updated credentials, so you can detect unauthorized changes.

Use different credential aliases for different environments: dev, staging and production each have their own HR system credentials. This ensures that a developer working on an integration in dev cannot accidentally authenticate to production data. Connections can be environment-specific or shared if the external system is the same across environments.

Lifecycle and Credential Rotation

Plan for credential rotation. Many organisations rotate API keys or passwords periodically. With Credential Alias, you rotate by updating the alias record. The integration flow does not need to be redeployed or paused. Create the new credential in the alias, test it with a flow run, and then make it active. If the new credential fails, rollback is just changing the alias back to the old credential.

Some external systems support multiple active credentials for a period so you can rotate gradually. Coordinate with the external system to understand rotation windows and whether multiple credentials can be active simultaneously. If not, plan rotation during a maintenance window when flows are paused.

Connection Types and Authentication Methods

Connections support multiple authentication types depending on the external system. Basic auth uses username and password. OAuth uses client credentials or token flows. Certificate-based auth uses client certificates for mutual TLS. API key auth stores the key in the credential alias. Choose the authentication method that the external system requires and that your security policy allows. Basic auth over HTTP is risky; use HTTPS or certificate-based auth for sensitive systems. OAuth is preferred for third-party integrations because it supports token expiry and limited scope.

Choosing how many aliases an integration estate needs

The question that decides most of the later pain is not how to create an alias but how many of them to create. An integration owner who builds one alias per connection ends up with dozens of near-identical secrets, each needing its own rotation. An owner who builds one alias for the whole platform gives every integration the same identity, so a leaked secret exposes everything at once. The useful answer sits between those two extremes, and it depends on which identity the external system recognizes as the caller.

Many estates end up with the third pattern as a baseline and the second for integrations that write data into a system of record. Pure per-connection aliases are rarely worth the rotation burden. When you are unsure, ask the external system owner how many distinct service identities they are willing to issue. Their answer often settles the count faster than any internal debate.

Building the pair in an order that avoids broken jobs

The order of setup matters more than most teams expect. A connection that references an alias which does not yet hold a valid secret will fail in ways that look like network faults, and the team spends an afternoon checking firewalls. Build the pair in this sequence so that each record is complete before the next one depends on it.

1. Agree with the external system owner which identity the integration will act as, and what permissions that identity has in the vendor console.
2. Create the credential alias with the secret, using an administrator who holds the credential management role. Keep the secret out of description fields, script includes and update set notes.
3. Create the connection record with the host name the vendor documents for that environment, and select the alias you just created.
4. Run the connection test from the same kind of node the production job will use. If the target sits behind the firewall, that means a MID server, not an instance node.
5. Record the alias owner and the next rotation date in your change or service register, so the rotation has a named person before it has a deadline.
6. Only then reference the connection from the flow, the scripted REST message or the import set that depends on it.

Where setups fail in practice

Three failure modes recur in practice. The first is the test that passes for the wrong identity. A developer tests the connection while logged in as themselves, the test succeeds because the connection uses the alias and not the user, but the scheduled job runs under a service account the external system has not authorized (see discovery credential governance). The result is a job that fails overnight and a developer who insists the connection worked the day before.

The second is rotation in the wrong order. The vendor generates a new secret and retires the old one, but the alias still holds the old value. Scheduled runs fail until someone notices the error in the job log. The fix is procedural: create the new secret first, update the alias, run the test, and only then retire the old secret in the vendor console. Some vendors allow two active secrets for a window, which makes this safer, but you should confirm that before you plan around it.

The third is copied configuration. Cloning a production instance into a sub-production sandbox copies records, and if the override that swaps the alias was never created, the sandbox quietly calls the production system. Treat the alias and connection as environment-specific records in your cloning checklist, and verify the host after every refresh.

Telling whether the setup is healthy

A healthy connection is one whose failures are readable. Check these points each quarter, and after any platform upgrade that touches the credential store:

• The connection test passes for the identity the scheduled job runs as, not only for an administrator.
• A failed call writes a clear error to the job or integration log that names the connection, rather than returning an empty result that looks like no data.
• Every alias has a named owner and a rotation date in a register that someone reviews.
• Sub-production aliases point to non-production hosts, and a sample of production aliases has been checked against the vendor console.
• Exported update sets contain no secret values.

When a shared connection is the wrong tool

A single connection serving many unrelated flows is convenient but makes troubleshooting slow. When one flow starts sending heavy traffic, the shared connection’s rate and error profile changes for every other flow that depends on it. If the flows have different owners, separate their connections even when they point at the same host. The cost is a few extra records; the benefit is that a problem in one team’s integration does not look like a problem in another team’s.

Questions to settle before go-live

Questions teams raise about aliases and connections

Can a flow fail over from one alias to another automatically?

Not by itself. A connection points at one alias, so failover between two secrets has to be designed as a deliberate pair of connections with logic that chooses between them, and that logic needs its own testing. Many teams prefer to fix the primary secret quickly rather than build automatic switching, because switching hides the original fault.

Why does the connection test pass when the scheduled job fails?

The test often runs from a different node, under a different identity, and often at a different time of day when the external system’s rate limits are not in effect. Compare the node, the user and the time of the failing run with the test before you change any credentials.

Should integrations use a personal user account?

Avoid it. A personal account ties the integration to someone’s employment, password policy and mailbox. When that person leaves, the integration stops. A dedicated service identity with the narrowest permissions the vendor allows is easier to audit and to rotate.

Do update sets carry the secret?

They should not. Promote the connection and the alias structure through the normal path, then enter the secret in the target environment through the credential management interface. Confirm after promotion that the value differs from the source environment.

Next step

Start with the alias list.