Inbound REST API Keys for Event Management Connectors

[charleselite]

Say goodbye to Basic Auth with Event Management! With the Washington release, the platform introduces the capability to set up Inbound REST API keys. When connecting systems, the most often preferred authentication method is API keys, as they eliminate concerns about OAuth expirations or the use of usernames and passwords with Basic Auth. API keys are straightforward to use, requiring merely an HTTP header or query parameter.

 

Previously, API keys could only be utilized for outbound REST requests. However, with the introduction of this new feature, it is now possible to create API keys for inbound REST requests. This enhancement allows for the creation of keys, thereby facilitating easier control over API access and ensuring secure and efficient system integration.

This is a great resource on the platform level features that we are going to leverage: Inbound REST API Keys

 

IMPORTANT: If you want multiple ways to authenticate, you need to add a profile for each way. i.e. Basic, Token, OAuth.

 

 

Applying this concept to Event Management Connectors

 

For Event Management Connectors, the process is a little different. But setup would allow you to send in events with a URL, no headers or authentication layers required from the source system. For example: https://webhooks.mysite.com/secrettoken

1. Verify the plug API Key and HMAC Authentication (com.glide.tokenbased_auth) is activated. (if not installed, install this plugin).

2. Change your Scope to: Event Management Connectors

3. 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. 

   5. Provide a descriptive name in the Name field.
4. In the Auth Parameter field, add the Query Parameter for x-sn-apikey.

Optional: if you prefer auth headers or want both options, add: Auth Header record for x-sn-apikey.

 

 

If you want BOTH, Basic and Token available you need to create another Authentication Profile. 

1. Create the Inbound Authentication Profile for Basic Auth:

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

2. Click New.
3. Select Create standard http authentication profiles 
4. Create a name, type = Basic and add Allow Access Policy under the authentication Policies

 

NEXT: Create the REST API key for each specific integration

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

2. Click New.
3. Provide a descriptive name, like the name of the integration and select a user.
   The user needs to be created with the evt_mgmt_integration role. Create a new one on the sys_user table to use here to facilitate the right access.

4. Unlock Auth Scope and add: UserAccount
   
   

5. 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 query parameter (or header) value when your other system sends a REST API request to ServiceNow.

Repeat this step, for each integration that needs an API token.

Create and Apply the API Access Policy

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

3. Click New.
4. Provide a descriptive name like Event Mgmt Connectors, and select the REST API: Event Connectors

** remember you need to be in the event mgmt. connectors scope for this to work.

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

NOTE: Add all the Authentication Profiles you created earlier, BASIC, OAuth, Token. If you do not have a profile for each method listed here, they will not work. 

5. Click Submit.

RESULTS:

Now you are ready to start sending events. In your monitoring tool you can send events either with the header or the query param: x-sn-apikey.

For example: https://[INSTANCENAME].service-now.com/api/sn_em_connector/em/inbound_event?source=[SOURCENAME]&sys_id=[SYSID OF PUSH CONNECTOR INSTANCE]&x-sn-apikey=[AUTH TOKEN]

[Community Alums]

{

    "error": {

        "message": "User Not Authenticated",

        "detail": "Required to provide Auth information"

    },

    "status": "failure"

}

getting this error while executing the event push , what could be the possible reason?

[SSakkirala]

Yes, We are recieving an error too.

We are trying to use this from an application called thousandeyes. 
We are reciveing the following error.

@charleselite , Any idea on how to resolve this. 
Our user has "web_service_admin" and evt_mgmt_integration" roles. 
Tried using push connector sys_id or instance sys_id for [SYSID OF PUSH CONNECTOR INSTANCE]. Still no result. Please respond.

[karanpreet]

@SSakkirala and @Community Alums Can you check the complete URL where you're sending the events?

In my case, I had followed all the steps but I was sending the events to the instance using the instance event push URL: <instance>/api/global/em/jsonv2 instead of sending to a specific connector i.e. <instance>/api/sn_em_connector/em/inbound_event?source=[SOURCENAME]

In case you're doing the same, consider creating an API access policy for that endpoint. To do the same:

1. Navigate to All > System Web Services > API Access Policies > REST API Access Policies
2. Create a new access policy.
3. Give it an appropriate name.
4. Under REST API select "Inbound Event"
5. The REST API path should show up as global/em
6. Add all the required Authentication profiles
7. Test again

In case you're using a tool like Postman, it's possible that it retained the cookies allowing it to use an existing session. You can disable the cookie jar in the settings for this request to ensure you're seeing the correct results.

[Community Alums]

My API URL was right, it worked fine for me after including all the authentication profiles and I have checked the Global checkbox as well. 

[Shanti7]

Hi @charleselite , do we need to create the Authentication profiles when receiving the alerts to MID server too?

[charleselite]

@Shanti7 This is now fully supported and shipped OOB with the latest version of the Event Mgmt Connectors Plugin. Update that plugin and you should get the full set of profiles and everything you need. with that update you just need to generate the token and start using it!

RE: Mid Servers as the collector - It is controlled at the api endpoint level. Since the path is a little different: /api/mid/em/inbound_event. I think you would need to setup the auth profiles for that target api endpoint. 

[Shanti7]

Thank you @charleselite  for the response. I have already found the link you shared and our API is working fine.

[Corrie Van Wyk]

Hi @charleselite 

I have updated to the latest version of the app.
I have created a user with all the relevant roles.

I have created the API key in the sn_em_connector scope

But from postman when I try to connect to the below endpoint I still get the error below.
Any thoughts:

https://*****service-now.com/api/sn_em_connector/em/inbound_event?source=aws

{"error":{"message":"User Not Authenticated","detail":"Required to provide Auth information"},"status":"failure"}

[ayla74108]

Thanks for the detailed walkthrough, Charles! This makes setting up inbound REST API keys for Event Management much clearer. The step-by-step instructions for creating authentication profiles and API keys will be really helpful for anyone integrating external systems. Excited to try this out in our instance!