Inbound REST API Keys

[Chuck Tomasi]

I've said it before, I love integrations! REST APIs are among my favorites. When I'm connecting systems to other systems, my preferred authentication method is API keys. No need to be concerned about OAuth expirations or (shudder) usernames and password with Basic Auth. API keys are easy to use - they are just an HTTP header or query parameter. Until now API keys could be used with outbound REST requests. However, with the Washington D.C. release we've introduced the ability to create API keys for inbound REST requests! Now you can create keys and easily control who has access to what APIs.

 

The Plugin

First, navigate to All > Admin Center > Application Manager and verify the plug API Key and HMAC Authentication (com.glide.tokenbased_auth) is activated. It should be, but for some reason if it isn't, go ahead and activate it.

Create the Inbound Authentication Profile

1. Navigate to All > System Web Services > API Access Policies > Inbound Authentication Profile.
   
   
   
   

2. Click New.

3. Click Create API Key authentication profiles.
   
   

   

4. Provide a descriptive name in the Name field.

5. In the Auth Parameter field, add either the Query Parameter or Auth Header record for x-sn-apikey.

   The Auth Parameter is used to determine how incoming requests are to send the API key (either as a query parameter or header.) For this example, I'm going to use the Header. You can choose your own adventure - feel the power!

   Tip: The complete list of Auth Paramters is available by navigating to All > System Web Services > API Access Policies > REST API Auth Parameter.

6. Click Submit.
   
   

   

Create the REST API key

1. Navigate to All > System Web Services > API Access Policies > REST API Key.
   
   

   
   
   

2. Click New.

3. Provide a descriptive name and select a user.
   
   

   The user is used to determine what data can be accessed to the API. This is similar to using Basic Auth.
   
   

   Tip: Consider using a non-user (e.g. service) account for your APIs rather than an actual employee. If the employee leaves and their account is deactivated, your API could stop working.

4. Use the form menu and choose Save.

   The system generates a token and saves it in the Token field. To see the token, use the lock icon and copy the contents display below the field. This is your header (or query paramter) value when your other system sends a REST API request to ServiceNow.

   Tip: Copy the token for testing.

   

The API Access Policy

1. Navigate to All > System Web Services > API Access Policies > REST API Access Policies.
   
   

   
   
   

2. Click New. For this example, we'll create a new one, although you can use the same policy with multiple API keys if you chose.

3. Provide a descriptive name, and select the REST API you want to use. We'll pick the table API for simplicity - again, choose your own adventure!

   On the right side of the form are a series of checkboxes. As you uncheck them, fields on the left appear. Use these to limit this policy to a specific method (e.g. GET, POST), or resources in that API, or even a version of the API. The flexibility is really powerful.

4. Add your new API Authentication Profile to the embedded list on the form.

5. Click Submit.

   

That's it! We're ready to test!

Test Your API Key

Rather than set up a third party system and get into the details, we'll use a standard testing tool to send a REST request to the instance. For this example, I'll be using Insomnia. The steps are very similar to Postman. In general,

1. Create a new request.

2. Select the protocol (REST) and method (GET).

3. Provide an endpoint. For example: https://yourinstance.service-now.com/api/now/table/incident

4. Add the header (or query parameter) x-sn-apikey.
   
   

   Wait, where did THAT come from?! Remember that parameter name we selected? It was in the list. If you don't recall, go back to the REST API Auth Parameters and look again. If you chose a different auth parameter be sure to use the proper name in the REST request!
   
   

5. Paste the value of the token copied earlier.

6. Send your request!
   
   

   

Hopefully you got a beautiful 200 request and the payload looks nicely formatted and full of data. If not, you'll need to do a little troubleshooting. Common issues may include:

• Typo in the parameter name.

• Incorrect token.

• The user record associated with the key may not have access to the data (check their roles, ACLs, etc).

 

Conclusion

API keys make managing access between systems quite simple. With the Washington D.C. release (and beyond), you can generate keys and access policies to your APIs for full control and easy of maintenance.