Connecting ServiceNow to external systems via REST APIs is fundamental. While authentication can be complex, API Key credentials offer a straightforward method. This article explains how these credentials work for outbound REST API calls, when to use them, and essential security considerations.
Understanding the API Key Credential Setup
An API Key credential allows you to store a static key or token that ServiceNow can automatically send with outbound REST requests.
For this article I have created a demo credential.
Let's look at the basic components:
- Connection Alias: A logical name that abstracts the actual connection details. This is what your Flow Designer actions or scripts will reference.
- Connection: Links the alias to a specific endpoint URL and is where you associate your credential.
- Credential: This is where your API Key is stored. For this demonstration, I'll use this_is_an_api_key.
How API Key Credentials Work Behind the Scenes
When you use an API Key credential, ServiceNow handles the injection of this key into your outbound requests. Let's see it in action:
Action Setup: Create an action in Flow Designer and add a REST Step. Select the Connection Alias you configured.
Initial Observation (Flow Execution - Headers): If you test this action without explicitly defining any headers in the REST step, you'll notice the headers might appear empty in the Flow Execution context.
This is because ServiceNow's credential framework automatically injects the API Key at runtime, just before the request is sent. It's not visible as a configured header within the Flow Designer step itself.
Confirming Injection (Outbound HTTP Logs): This happens behind the scenes when the request is actually sent. Check your Outbound HTTP Logs (syslog_http_client.list) for the corresponding transaction. You have to enable capturing Request & Response details to view this.
As you can see, the API Key is automatically sent in the Authorization header, even if you just provided the key itself in the credential record. This is a default behavior for the API Key credential type.
Scenarios for Using API Key Credentials
API Key credentials are ideal for integrations where:
- Static Key Authentication: The external system uses a long-lived, static key or token that doesn't frequently change.
- Authorization Header Expectation: The external system expects the authentication token to be sent in the Authorization header.
Handling Custom Header Requirements
What if the external system expects the token in a different header or as a query parameter
- You can explicitly define the required header (e.g., X-API-KEY) or query parameter in your REST step, then pass the credential value using Credential variable in the flow designer.
- If the system expects the token in a different format, then the API Key can be amened as per the requirement.
Examples:
Jira Server often uses Personal Access Tokens (PATs) for API authentication, which are expected in the Authorization header as a Bearer token.
- Jira Spoke Connection:
When creating connection alias for your Jira spoke, you can create a credential of type API Key credential in ServiceNow, you can prepend "Bearer " to your Jira PAT as the API Key. For example, if your PAT is abcde12345, you would store Bearer abcde12345 in the API Key field.
- ServiceNow DevOps Change Velocity: ServiceNow DevOps Change Velocity simplifies this further. During tool onboarding, when connecting to Jira, you typically don't need to manually add "Bearer ". The system is designed to automatically prefix the provided PAT with "Bearer " before creating the underlying API Key credential.
Important Header Precedence:
Be aware of how ServiceNow handles header conflicts:
- Authorization Header Override: If you explicitly define an Authorization header within your REST step, it will override the Authorization header automatically generated from your API Key credential. The credential's value will not be sent in that case.
- Custom Header Coexistence: If you define a different custom header (e.g., X-Custom-Auth) in your REST step, both your custom header and the Authorization header from the API Key credential will be sent.
- This dual-header behavior could cause issues with some external systems that are sensitive to unexpected authentication headers, potentially leading to a 401 Unauthorized response if they attempt to authenticate via an unintended method.
Conclusion:
API Key credentials offer a straightforward method for ServiceNow's outbound REST authentication. They automatically inject static tokens, typically into the Authorization header, simplifying setup. Understanding this automatic injection and header precedence is crucial, especially when customizing header requirements. API Keys are valuable for specific integration scenarios but always balance their ease of use with your organization's security guidelines.
