ServiceNow: Scripted REST API with API Key

Introduction

Setting up API key authentication for scripted REST APIs in ServiceNow can streamline your integration and ensure secure access to your APIs. This guide will walk you through each step, from setting up an authentication profile to testing the integration. By following these steps, you’ll have a secure and well-configured API key authentication process ready for use with your ServiceNow REST APIs.

Step 1: Set Up an Authentication Profile

To begin, configure an authentication profile in ServiceNow to manage how your API keys are processed.

1. Navigate to the Inbound Authentication Profile Section: Go to System Web Services > API Access Policies > Inbound Authentication Profile in your ServiceNow instance.
2. Create an API Key Authentication Profile:
   • Select the option to create a new profile dedicated to API Key authentication.
   • Define the appropriate authorization parameter. Typically, you can set this to authorize users via the Auth header or Query parameter, depending on the level of security required by your integration.

   Choosing the Auth header ensures that sensitive information is not exposed in the URL, which is generally recommended for added security. Alternatively, if you prefer a simpler setup, using the Query parameter is another option, though slightly less secure.

Step 2: Set Up an API Key

The next step involves creating the actual API key that will be used for authentication.

1. Navigate to the REST API Key Section: Go to System Web Services > API Access Policies > REST API Key.
2. Create a New API Key:
   • Define a Name for the API key that is easily identifiable for future reference.
   • Select the User who will have access to this API key. This user should have the appropriate permissions to interact with the specified REST APIs.
   • Copy the Token generated for this key. The token is a unique identifier for API access and will be used in the authorization part of your API calls. Ensure that this token is stored securely, as it provides direct access to your REST APIs.

Step 3: Configure an API Access Policy

With the API key created, you need to configure an access policy to control the conditions under which the API key can access your scripted REST APIs.

1. Navigate to REST API Access Policies: Go to System Web Services > API Access Policies > REST API Access Policies.
2. Create a New API Access Policy:
   • Define a Name for the access policy that reflects its purpose.
   • Select the REST API (specifically, the scripted REST API) that this policy will apply to.
   • Configure additional attributes as needed, such as whether the policy should Apply to all methods (e.g., GET, POST, PUT, DELETE) and any other conditions relevant to your setup. Customizing these attributes ensures that the access policy fits the intended use case and restricts API key usage as needed.

Step 4: Test the Integration

Now that your API key and access policy are configured, it’s essential to test the integration and verify that everything is working as expected.

1. Test the API Key Authentication: Use your dedicated API token (generated in Step 2) and insert it in the manner specified in your authentication profile—either in the x-sn-apikey header or as a query parameter, depending on the setup.
2. Verify Successful Authentication:
   • Send a request to your scripted REST API with the API key. Confirm that the request is successfully authenticated using the API key token.
   • Check that the API responses are returned as expected and that no authentication errors occur.
   • If there are any issues, double-check the access policy settings and the way the API key is passed in the request headers or parameters.

Conclusion

Setting up API key authentication for scripted REST APIs in ServiceNow enhances security and provides a reliable means to control access. By carefully following these steps—configuring an authentication profile, creating an API key, setting up an API access policy, and testing the integration—you’ll establish a secure foundation for managing API access. This setup also gives you the flexibility to adjust permissions, ensuring your APIs are accessed securely and as intended.

By implementing this API key authentication method, you’ll be well-prepared for secure ServiceNow REST API interactions, allowing authorized users to integrate with confidence.