Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.toktra.dev/llms.txt

Use this file to discover all available pages before exploring further.

Toktra’s ITSM integration turns policy violations into actionable tickets in your existing service management platform. Tickets are created automatically when a violation fires, and status changes in your ITSM flow back into Toktra via a webhook receiver.

​
Supported platforms

ServiceNow

REST API — incidents created via the Table API (/api/now/table/incident) with Basic authentication.

Jira Cloud

REST API v3 — issues created via /rest/api/3/issue with Basic authentication (email + API token).

​
Configuring an ITSM connector

1

Open the Integrations page

In your Toktra dashboard, go to Integrations → ITSM (/integrations/itsm). Click Add connector.
2

Choose a platform

Select ServiceNow or Jira from the platform dropdown.
3

Enter credentials

Fill in the platform-specific fields described in Required credentials below.
4

Set defaults

Enter a Default project (Jira project key, e.g. SEC) or Assignment group (ServiceNow) and a Default issue type (e.g. Bug, Incident). These are used when creating tickets from policy violations.
5

Test the connection

Click Test connection. Toktra creates a low-severity test ticket in your ITSM and shows you the external ticket ID. Verify the ticket appears before saving.
6

Save and activate

Toggle Active on, then click Save.

​
Required credentials

FieldDescription
Instance URLThe base URL of your ServiceNow instance, e.g. https://company.service-now.com.
UsernameA ServiceNow user with the itil role and write access to the incident table.
PasswordPassword for the user above.
Assignment groupOptional. The group name to assign created incidents to, e.g. IT Security.
Environment variables
ITSM_SERVICENOW_INSTANCE=https://company.service-now.com
ITSM_SERVICENOW_USERNAME=toktra-svc
ITSM_SERVICENOW_PASSWORD=your-password
Toktra uses HTTP Basic authentication (Authorization: Basic <base64(username:password)>). For production use, create a dedicated service account with the minimum required permissions.

​
Automatic ticket creation

When the Toktra policy engine evaluates a violation, it automatically calls your active ITSM connector. Tickets are created with:
  • Title: [Toktra] <event_type>: <summary> — e.g. [Toktra] policy_violation: max-tokens exceeded
  • Description: Full JSON violation payload including user, model, provider, and policy details
  • Severity mapping: See Severity mapping below
  • Labels (Jira): toktra, ai-policy, and the severity level
Toktra records the external ticket ID and provides a direct link to the ticket in the Incidents page.

​
Severity mapping

Toktra severity levels map to native ITSM priority fields as follows:
Toktra severityServiceNow urgencyServiceNow impact
critical1 — High1 — High
high2 — Medium2 — Medium
medium2 — Medium3 — Low
low3 — Low3 — Low
ServiceNow sets the incident priority automatically from urgency + impact using the default priority matrix.

​
Bidirectional sync

When a ticket is resolved or updated in your ITSM, you can push the status change back to Toktra. Configure your ITSM to send a webhook to: 
POST https://api.toktra.io/v1/integrations/itsm/webhook/{org_id}
The webhook payload should include:
ITSM webhook payload
{
  "external_ticket_id": "INC0012345",
  "status": "resolved",
  "resolution": "Policy configuration updated to allow this usage pattern.",
  "notes": "Reviewed by security team — false positive.",
  "updated_by": "jane.doe@company.com"
}
Toktra matches the external_ticket_id to a known ticket and updates its status in the Incidents page. Valid status values are open, in_progress, resolved, and closed.
Toktra does not currently verify an HMAC signature on inbound ITSM webhooks. Restrict access to the webhook endpoint at the network level (e.g. allowlist your ITSM’s IP ranges).

​
Creating tickets manually

You can create an ITSM ticket for any incident directly from the Toktra Incidents page:
1

Open the incident

Go to Incidents and click the incident you want to escalate.
2

Create ticket

Click Create ITSM ticket. Select the ITSM connector to use if you have more than one configured.
3

Review and submit

The ticket title and description are pre-filled from the incident. Edit if needed, then click Submit.
You can also create ITSM tickets directly from Slack using the /toktra-alerts command. See the Slack integration page.

​
Viewing linked tickets

All tickets created by Toktra appear in Integrations → ITSM → Tickets with their external IDs and direct links. The table shows ticket status as last reported by your ITSM webhook.