Skip to main content
Connect your ServiceNow instance to Athena so each member can search records, read tickets with their comments and work notes, search knowledge articles, and update records as their own ServiceNow account. Your ServiceNow roles, ACLs and data policies apply unchanged. Athena sees exactly what you can see in ServiceNow, nothing is shared through a service account, and every change Athena makes is recorded under your name.
Setup involves two people. Your ServiceNow administrator registers an OAuth application in your instance. Athena Intelligence then registers that application for your workspace. Members can only connect after both are done.

​
Step 1 — Register an OAuth application in ServiceNow (ServiceNow admin)

Register one application per instance. If members should connect both production and a sub-production instance, register one in each.
  1. In your instance, go to System OAuth → Application Registry → New and choose Create an OAuth API endpoint for external clients.
  2. Name it, for example Athena, and set the Redirect URL:
    For private or VPC deployments, replace api.athenaintel.com with your environment’s Athena API host. ServiceNow requires an exact match.
  3. Leave Public Client off.
  4. Keep a non-zero Refresh Token Lifespan. The default is 100 days. Athena refuses a connection that comes back without a refresh token.
  5. Save the record, then copy the Client ID and the generated Client Secret.
  6. Send the Client ID, the Client Secret and your instance address (for example acme.service-now.com) to Athena Intelligence through a secure channel.
By default the application uses ServiceNow’s standard useraccount scope: Athena can do what the signed-in member can do, and nothing more. To fence Athena to specific REST APIs, create a custom auth scope and attach it to those APIs under REST API Auth Scopes. Then ask Athena Intelligence to request that scope instead. The scope must cover the Table API (/api/now/table) and the current-user lookup (/api/now/ui/user).

​
Step 2 — Athena registers the application for your workspace

Athena Intelligence adds a servicenow_direct integration for your workspace. It holds the Client ID, the encrypted Client Secret and your instance host. Secrets are encrypted at rest and never returned to the browser. Once the integration is saved, the ServiceNow card on the Integrations page is available to every member. Until then, the card says the integration isn’t set up for the workspace yet.

​
Step 3 — Connect your account (each member)

  1. Navigate to Integrations and click Connect ServiceNow on the ServiceNow card, under Project Management & Ticketing.
  2. Your instance’s sign-in page opens in a popup. Sign in if you are not already, then click Allow. There is no picker step on the Athena side: Athena stores your encrypted tokens and confirms the connection with your ServiceNow email.
  3. If your workspace has more than one instance registered, pick the instance before connecting. To add another instance later, click Connect another ServiceNow instance.

​
What Athena can do

Once connected, the ServiceNow toolkit gives agents these tools. A few behaviors to know:
  • Plain-language requests work. Ask “show my open P1 incidents” or “summarize the work notes on INC0012345”. Athena builds the ServiceNow query for you.
  • Reference and choice fields show two values. For example, Beth Anglin [46d4…] or In Progress [2]. The second value is what ServiceNow stores, and Athena uses it when it updates a record.
  • Notes are internal by default. Athena adds a work note unless you ask for a customer-visible comment.
  • Platform tables are never written. Athena never writes ServiceNow platform tables (sys_*), whatever your roles allow.
  • Read tools work in automations. The read tools can run as steps, as the member who runs them. Write tools are available only in chat, where you can approve them.

​
Run automations when records change

Your ServiceNow instance can tell Athena when a record is created or updated, so an automation can run on it: triage a new P1 incident, for example, or summarize a change request when its state moves.
  1. Ask Athena Intelligence for your instance’s webhook details. You receive a URL, a secret and a Business Rule script.
  2. In ServiceNow, go to System Properties and create the property named in the webhook details (it starts with athena.webhook.secret.) with type password2. Set its value to the secret.
  3. Go to System Definition › Business Rules › New. Pick the table to watch, for example Incident. Set When to after, check Insert and Update, turn on Advanced, and paste the script. The script sends the change from a background job, so saving a record never waits on Athena, and it retries a failed delivery a few times.
Automations can then use these events:
  • servicenow.incident.created and servicenow.incident.updated
  • servicenow.record.created and servicenow.record.updated, for other tables
Each event carries the record’s number, short description, state, priority, assignment, a link to the record, and the fields that changed.

​
Use ServiceNow from a computer

On a computer with your ServiceNow connection attached under Connected Catalogs:
  • SERVICENOW_INSTANCE_URL holds your instance’s address.
  • SERVICENOW_API_URL holds its REST base, https://<instance>/api/now.
  • athena-catalog-token servicenow_direct prints a short-lived access token for your connection.
athena-catalog-token returns the current token while it is fresh and gets a new one otherwise. With more than one ServiceNow instance attached, pass the catalog’s asset ID instead of servicenow_direct. The computer acts as you, so anyone you share it with can use your ServiceNow access from it: attach your connection only to a computer you don’t share.

​
Token lifecycle & troubleshooting

  • Everything is per-user. Results always reflect your ServiceNow roles and ACLs, and every change is attributed to you.
  • “Reconnect ServiceNow.” A connection lasts as long as the application’s refresh token lifespan (100 days by default). An administrator can also revoke it under System OAuth → Manage Tokens. Either way, reconnecting from the Integrations page fixes it.
  • “Invalid redirect_uri” in the popup. The application’s Redirect URL doesn’t exactly match the one in step 1.2.
  • “ServiceNow did not accept the new sign-in.” The instance refused Athena’s request to identify you. If you use a custom auth scope, make sure it covers the Table API and the current-user lookup.
  • “Your roles or ACLs do not allow it.” ServiceNow refused the request for your account, for example because you lack the itil role needed for incidents. Ask your ServiceNow administrator for the role. Athena cannot widen your access.
  • Rate limits. If your instance limits REST requests, Athena reports how long to wait instead of retrying.

​
Disconnecting

Open the ServiceNow connection in Athena and click Disconnect. Athena revokes its access on your instance and removes your stored tokens. Other instances you connected stay connected.