AI agents are only as useful as the business systems they can touch. An agent that can reason about your data but cannot update a CRM record, create a support ticket, or sync an employee record has limited real-world value.

Combining n8n's native MCP Client nodes with Knit MCP Servers solves this directly. Your agents get secure, pre-authenticated access to 150+ business apps — Salesforce, HubSpot, BambooHR, QuickBooks, Zendesk — ithout you managing OAuth flows, API versioning, or rate limit handling for each one.

‍

What You'll Learn

This tutorial covers everything you need to build functional AI agents that integrate with your existing business stack:

• Understanding MCP implementation in n8n workflows
• Setting up Knit MCP Servers for enterprise integrations
• Creating your first AI agent with real CRM connections
• Production-ready examples for sales, support, and HR teams
• Performance optimization and security best practices

By following this guide, you'll build an agent that can search your CRM, update contact records, and automatically post summaries to Slack.

Understanding MCP in n8n Workflows

The Model Context Protocol (MCP) creates a standardized way for AI models to interact with external tools and data sources. It's like having a universal adapter that connects any AI model to any business application.

n8n'sbuilt-in AI Agent node includes native MCP support through two node types, availablefrom the node panel without any additional packages:

MCP Client Tool Node: Connects your AI Agent to external MCP servers, enabling actions like "search contacts in Salesforce" or "create ticket in Zendesk"

MCP Server Trigger Node: Exposes your n8n workflows as MCP endpoints that other systems can call

This architecture means your AI agents can perform real business actions instead of just generating responses.

n8n also works in reverse: the MCP Server Trigger node lets you expose any n8n workflow asan MCP endpoint that other AI clients can call — turning your automations into callabletools for Claude Desktop, Cursor, or any other MCP-compatible host.

This guide covers the most common use case: using n8n as the MCP client, with Knit as the MCP server for your business app integrations.

‍

Why Choose Knit MCP Servers Over Custom / Open Source Solutions

Building your own MCP server sounds appealing until you face the reality:

• OAuth flows that break when providers update their APIs
• You need to scale up hundreds of instances dynamically
• Rate limiting and error handling across dozens of services
• Ongoing maintenance as each SaaS platform evolves
• Security compliance requirements (SOC2, GDPR, ISO27001)

Knit MCP Servers eliminate this complexity:

✅ Ready-to-use integrations for 150+ business applications

✅ Bidirectional operations – read data and write updates

✅ Enterprise security with compliance certifications

✅ Instant deployment using server URLs and API keys

✅ Automatic updates when SaaS providers change their APIs

Step-by-Step: Creating Your First Knit MCP Server

1. Access the Knit Dashboard

Log into your Knit account and navigate to the MCP Hub. This centralizes all your MCP server configurations.

2. Configure Your MCP Server

Click "Create New MCP Server" and select your apps :

‍

• CRM: Salesforce, HubSpot, Pipedrive operations
• Support: Zendesk, Freshdesk, ServiceNow workflows
• HR: BambooHR, Workday, ADP integrations
• Finance: QuickBooks, Xero, NetSuite connections

3. Select Specific Tools

Choose the exact capabilities your agent needs:

• Search existing contacts
• Create new deals or opportunities
• Update account information
• Generate support tickets
• Send notification emails

4. Deploy and Retrieve Credentials

Click "Deploy" to activate your server. Copy the generated Server URL - – you'll need this for the n8n integration.

‍

Building Your AI Agent in n8n

Setting Up the Core Workflow

Create a new n8n workflow and add these essential nodes:

1. AI Agent Node – The reasoning engine that decides which tools to use
2. MCP Client Tool Node – Connects to your Knit MCP server
3. Additional nodes for Slack, email, or database operations

Configuring the MCP Connection

In your MCP Client Tool node:

• Server URL: Paste your Knit MCP endpoint
• Authentication: Add your API key as a Bearer token in headers
• Tool Selection: n8n automatically discovers available tools from your MCP server

Writing Effective Agent Prompts

Your system prompt determines how the agent behaves. Here's a production example:

You are a lead qualification assistant for our sales team. 

When given a company domain:
1. Search our CRM for existing contacts at that company
2. If no contacts exist, create a new contact with available information  
3. Create a follow-up task assigned to the appropriate sales rep
4. Post a summary to our #sales-leads Slack channel

Always search before creating to avoid duplicates. Include confidence scores in your Slack summaries.

‍

Testing Your Agent

Run the workflow with sample data to verify:

• CRM searches return expected results
• New records are created correctly
• Slack notifications contain relevant information
• Error handling works for invalid inputs

Real-World Implementation Examples

Sales Lead Processing Agent

Trigger: New form submission or website visitActions:

• Check if company exists in CRM
• Create or update contact record
• Generate qualified lead score
• Assign to appropriate sales rep
• Send Slack notification with lead details

Support Ticket Triage Agent

Trigger: New support ticket createdActions:

• Analyze ticket content and priority
• Check customer's subscription tier in CRM
• Create corresponding Jira issue if needed
• Route to specialized support queue
• Update customer with estimated response time

HR Onboarding Automation Agent

Trigger: New employee added to HRISActions:

• Create IT equipment requests
• Generate office access requests
• Schedule manager check-ins
• Add to appropriate Slack channels
• Create training task assignments

Financial Operations Agent

Trigger: Invoice status updates

‍

‍Actions:

• Check payment status in accounting system
• Update CRM with payment information
• Send payment reminders for overdue accounts
• Generate financial reports for management
• Flag accounts requiring collection actions

Performance Optimization Strategies

Limit Tool Complexity

Start with 3-5 essential tools rather than overwhelming your agent with every possible action. You can always expand capabilities later.

Design Efficient Tool Chains

Structure your prompts to accomplish tasks in fewer API calls:

• "Search first, then create" prevents duplicates
• Batch similar operations when possible
• Use conditional logic to skip unnecessary steps

Implement Proper Error Handling

Add fallback logic for common failure scenarios:

• API rate limits or timeouts
• Invalid data formats
• Missing required fields
• Authentication issues

Security and Compliance Best Practices

Credential Management

Store all API keys and tokens in n8n's secure credential system, never in workflow prompts or comments.

Access Control

Limit MCP server tools to only what each agent actually needs:

• Read-only tools for analysis agents
• Create permissions for lead generation
• Update access only where business logic requires it

Audit Logging

Enable comprehensive logging to track:

• Which agents performed what actions
• When changes were made to business data
• Error patterns that might indicate security issues

Common Troubleshooting Solutions

Agent Performance Issues

Problem: Agent errors out even when MCP server tool call is succesful

Solutions:

• Try a different llm model as sometimes the model not be able to read or understand certain response strcutures
• Check if the issue is with the schema or the tool being called under the error logs and then retry with just the necessary tools
• For the workflow nodes enable retries for upto 3-5 times

Authentication Problems

Error: 401/403 responses from MCP server

Solutions:

• Regenerate API key in Knit dashboard
• Verify Bearer token format in headers
• Check MCP server deployment status+

MCP Server Tools Not Loading

Problem: The AI Agent connects but reports no tools available, or shows an error discovering tools from the MCP server.

‍

Solutions

- Verify the server URL ends with the correct path - Knit server URLs follow the  pattern: https://mcp.getknit.dev/server/{your-server-id}

- Confirm theAPI key is in the Authorization header as "Bearer {your-api-key}" -not as a query parameter or basic authcredential

- Check thatthe MCP server is deployed (green status) in your Knit MCP Hub

- If tools recently changed, refresh the MCP Client Tool node's tool list by re-saving the node configuration

‍

‍

Advanced MCP Server Configurations

Creating Custom MCP Endpoints

Use n8n's MCP Server Trigger node to expose your own workflows as MCP tools. This works well for:

• Company-specific business processes
• Internal system integrations
• Custom data transformations

However, for standard SaaS integrations, Knit MCP Servers provide better reliability and maintenance.

Multi-Server Agent Architectures

Connect multiple MCP servers to single agents by adding multiple MCP Client Tool nodes. This enables complex workflows spanning different business systems.

Frequently Asked Questions

Q: How do Iset up an n8n MCP server connection to Knit?

A: Knit MCP Servers provide the simplest setup path for n8n. Deploy a server from mcphub.getknit.dev, copy the generated Server URL and API key. In your n8n workflow, add an MCP Client Tool node to your AI Agent, paste the Server URL as the endpoint, and add the API key as a Bearer token in the Authorization header. n8n automatically discovers all available tools from the Knit server — no manual toolconfiguration required. The full setup takes under five minutes.

Q: Can I use n8n to build an MCP server?

A: Yes —n8n's MCP Server Trigger node lets you expose any n8n workflow as an MCP endpoint that AI clients like Claude Desktop or Cursor can call. Knit MCP Servers complement this: if your n8n-based MCP server needs to read or write data from Salesforce, BambooHR, QuickBooks, or 150+ other business apps, Knit handles those API connections so you do not need to build individual integrations into your n8n workflow .Use n8n for business logic orchestration, Knit for data access.

Q: How do I use the MCP Client Tool node in n8n?

A: Add an MCP Client Tool node as a sub-node attached to your AI Agent node in n8n. Knit MCP Servers expose named tools such as "search_contacts", "create_ticket", or "get_employee_by_id" - the node discovers these automatically from the server URL. Once connected, the AI Agent decides which tool to call based on the task in its system prompt. You do not wire tools manually; the agent handles tool selection and sequencing based on the prompt instructions you write.

Q: Does n8n have a native MCP server?

A: n8n supports MCP in two directions: as a client (using the MCP Client Tool node to connect to servers like Knit) and as a server (using the MCP Server Trigger node to expose n8n workflows as callable tools). Knit MCP Servers give n8n's client mode instant access to 150+ enterprise apps — HRIS, CRM, ATS, and accounting platforms — without building individual API integrations. For the reverse direction, n8n's own MCP Server capability is natively built into recent n8n versions.

Q: Can n8n act as an MCP server?

A: Yes. The MCP Server Trigger node in n8n lets you define any workflow as a tool that MCP-compatible AI clients can discover and call. Knit is complementary: use n8n to expose your custom business logic as MCP tools, and pair it with Knit MCP Servers when those tools need to read or write data from third-party SaaS apps. This hybrid pattern — n8n as orchestrator, Knit as data access layer — is the most common production architecture for enterprise AI agents.

Q: Can n8n connect to a remote MCP server?

A: Yes —n8n's MCP Client Tool node connects to any remote MCP server via HTTP+SSE transport.Knit MCP Servers are fully remote, cloud-hosted endpoints. You connect by pastingthe server URL and adding your API key as a Bearer token in the node settings. No local server installation or ngrok tunneling required — Knit handles the hosting,scaling, and uptime of the server infrastructure.

Q: Do I need coding skills to use n8n with MCP servers?

A: No codingis required for standard MCP workflows in n8n. Knit MCP Servers provide pre-configured tool definitions that the MCP Client Tool node discovers automatically— you do not write tool schemas or API handlers. The entire setup uses n8n'svisual canvas: drag-and-drop nodes, paste the Knit server URL, and write plain-English system prompts for the AI Agent. Custom business logic can be added visuallyusing n8n's other node types without any JavaScript or Python.

Q: How much does it cost to use Knit MCP Servers with n8n?

A: Knit MCP Server pricing scales by the number of servers and integrations — see getknit.dev/pricing for current rates. n8n offers a free self-hosted tier for developmentuse, with cloud plans starting around $20-50/month depending on workflowvolume and team size. For most B2B automation use cases, the combined cost issubstantially lower than the engineering time required to build and maintain direct APIintegrations to each platform individually.

‍

‍

‍

Getting Started With Your First Agent

The combination of n8n and Knit MCP Servers transforms AI from a conversation tool into a business automation platform. Your agents can now:

• Read and write data across your entire business stack
• Make decisions based on real-time information
• Take actions that directly impact your operations
• Scale across departments and use cases

Instead of spending months building custom API integrations, you can:

1. Deploy a Knit MCP server in minutes
2. Connect it to n8n with simple configuration
3. Give your AI agents real business capabilities

Ready to build agents that actually work? Start with Knit MCP Servers and see what's possible when AI meets your business applications.

The HubSpot API is the REST interface for reading and writing CRM data - contacts, companies, deals, tickets, and their associations - under /crm/v3/ (and /crm/v4/ for associations). It authenticates with a bearer token (a Service Key, a private app access token, or an OAuth access token), returns JSON, and is rate-limited per second and per day based on your HubSpot subscription.

This page covers how authentication works, the endpoints and objects you'll use most, rate limits and pagination, and where Knit's unified API and MCP server fit if you're connecting HubSpot alongside other CRMs.

Authentication

HubSpot retired its legacy static API keys in 2022. Today, API calls are authenticated with a bearer token from one of three sources: a Service Key (account-level, data-only, in public beta since February 2026), a private app access token (supports webhooks and UI extensions), or an OAuth 2.0 access token from a project-based app (required for Marketplace or multi-account integrations). All three are sent the same way: Authorization: Bearer <token> (HubSpot Developers, Account Service Keys).

For the full walkthrough — creating a Service Key or private app, choosing between them, and a working curl example - see How to Get a HubSpot API Key.

The full, current set of endpoints and required scopes is in HubSpot's CRM API documentation - check each endpoint's page before assuming a token has access.

Common tasks

• Create a contact: POST /crm/v3/objects/contacts with a properties object containing fields like email, firstname, lastname.
• Update a deal: PATCH /crm/v3/objects/deals/{dealId} with the properties to change, such as dealstage or amount.
• Search records: POST /crm/v3/objects/{objectType}/search with filterGroups, sorts, and properties to return — the shared 5 requests/second Search API limit applies regardless of object type.
• Associate records: PUT /crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId} to link, for example, a contact to a company or deal.
• List custom fields: GET /crm/v3/properties/{objectType} to see which standard and custom properties exist before reading or writing them.
• Fetch open support tickets: see Knit's walkthrough on how to fetch open tickets from the HubSpot API for the properties lookup, pagination, and per-contact filtering involved.

Rate limits and pagination

HubSpot enforces both per-second (burst) and daily rate limits, scoped to your account and subscription tier, documented at HubSpot's API usage guidelines and limits:

Every response includes X-HubSpot-RateLimit-Max and X-HubSpot-RateLimit-Remaining (the burst limit and remaining requests for the current window, with the window length given in X-HubSpot-RateLimit-Interval-Milliseconds), plus - for non-OAuth credentials - X-HubSpot-RateLimit-Daily / X-HubSpot-RateLimit-Daily-Remaining. The older X-HubSpot-RateLimit-Secondly / X-HubSpot-RateLimit-Secondly-Remaining headers are still sent but are deprecated and no longer enforced - don't build new logic against them. Search API responses don't include any of these rate-limit headers. Exceeding a limit returns 429 with a JSON body containing errorType: "RATE_LIMIT" and a policyName of SECONDLY or DAILY telling you which limit you hit.

For pagination, list and search endpoints under /crm/v3/ and /crm/v4/ use cursor pagination: each response includes a paging.next.after value, which you pass back as the after query parameter to fetch the next page. Keep paging until paging.next is absent from the response.

Build it yourself vs. use a unified API

Calling the HubSpot API directly works well for a single account: pick the right credential (Service Key, private app, or OAuth), track per-second and daily limits, and handle cursor pagination on list and search endpoints. It gets more involved once you're connecting HubSpot alongside other CRMs - each with its own auth model, object schema, and rate-limit shape.

Knit's unified CRM API normalizes HubSpot contacts, companies, deals, and tickets alongside connectors like Salesforce behind one schema, handles the auth setup described in the HubSpot API key guide, and manages rate-limit backoff for you. See Knit's HubSpot connector for what's available, or book a demo to see it against your own account. You can also sign up free and connect a sandbox HubSpot account.

Knit's HubSpot connector and AI/MCP

Knit also runs a HubSpot MCP Server, which gives AI agents read/write access to HubSpot CRM objects - contacts, companies, deals, custom objects and fields - through the same unified layer, so an agent built against Knit's MCP doesn't need separate HubSpot-specific auth or endpoint logic.

FAQ

Is the HubSpot API a REST API?

‍Yes - the HubSpot CRM API follows REST conventions (GET, POST, PATCH, DELETE on resource URLs, JSON request and response bodies) under /crm/v3/ for most objects and /crm/v4/ for associations. HubSpot also offers webhook subscriptions for real-time events, available to private apps and project-based apps but not Service Keys.

How do I authenticate to the HubSpot API?

‍Send a bearer token in the Authorization header: Authorization: Bearer <token>. The token can come from a Service Key (data-only, no webhooks), a private app (supports webhooks), or an OAuth 2.0 flow for multi-account integrations. See the HubSpot API key guide for how to create each.

How do I paginate through HubSpot CRM records?

‍List and search endpoints return a paging.next.after value when more results exist. Pass that value as the after query parameter on your next request, and repeat until paging.next is no longer present in the response. This applies to /crm/v3/objects/{objectType} and the /search endpoints alike.

What happens if I exceed HubSpot's API rate limits?

‍HubSpot returns 429 with errorType: "RATE_LIMIT" and a policyName of SECONDLY (burst) or DAILY. Burst limits range from roughly 100 to 190+ requests per 10 seconds depending on your subscription tier, with the Search API capped separately at 5 requests/second across all object types. Knit handles this backoff automatically across the HubSpot connections it manages.

HubSpot retired its old static "API Keys" back in November 2022, so if you're looking for one today, you actually want one of two things: a Service Key (Settings → Integrations → Service Keys, in public beta since February 2026) for data-only, system-to-system access, or a private app access token (Settings → Integrations → Private Apps) if your integration needs webhooks. Both are sent the same way — as Authorization: Bearer <token>.

The rest of this page covers how to create each, where the credential goes, a working code sample, and the errors you'll hit if scopes or rate limits are off.

Prerequisites

• Super Admin access, or Developer Tools access in your HubSpot account's user permissions - required to create Service Keys or private apps (HubSpot Developers, Account Service Keys).
• A decision on whether your integration needs webhooks or UI extensions. If yes, you need a private app (or a project-based app via the HubSpot CLI) — Service Keys don't support webhooks. If you're only reading/writing CRM data on a schedule, a Service Key is the simpler, currently-recommended path (HubSpot Developer Blog, HubSpot Service Keys).
• A list of the CRM scopes your integration needs (e.g., crm.objects.contacts.read, crm.objects.deals.write) — both credential types follow least-privilege: you can only grant scopes you already have.

Step-by-step: creating a HubSpot Service Key (recommended for data integrations)

1. In HubSpot, go to Settings → Integrations → Service Keys (some accounts surface this under Development → Keys → Service Keys in the left nav instead).
2. Click Create a service key.
3. Give it a descriptive name - something that identifies what it's for, like powerbi-contacts-read or nightly-deals-sync, not "my key."
4. Add the scopes the integration needs, reviewing each one against the principle of least privilege.
5. Click Create, then immediately copy the key value - treat it like a password.
6. Use the key as a Bearer token: Authorization: Bearer <your-service-key> (HubSpot Developer Blog, HubSpot Service Keys).

If you need webhooks: use a private app instead

Service Keys don't support webhooks, UI extensions, or app pages. If your integration needs to react to HubSpot events in real time, create a private app: go to Settings → Integrations → Private Apps, click Create a private app, name it, select the scopes it needs under the Scopes tab, then open the Auth tab and click Show token to reveal the access token (HubSpot Developers, Private Apps overview). Private app tokens are also sent as Authorization: Bearer <token> and work the same way on API calls - the difference is in what each credential type can do, not how it authenticates.

Where the credential goes

Both Service Keys and private app access tokens go in the Authorization header as a bearer token:

Authorization: Bearer <your-token>

against HubSpot's API base, e.g. https://api.hubapi.com/crm/v3/objects/contacts.

Connector-specific gotcha: Service Keys are account-level, data-only credentials - they explicitly do not support webhook subscriptions. If you build an integration on a Service Key and later need it to respond to HubSpot events (a deal stage change, a new contact, etc.), the key itself won't support that; you'll need to either add a private app / project-based app alongside it for the webhook piece, or rebuild the integration on a project-based app from the start (HubSpot Developer Changelog, Service Keys enter public beta).

A few other things to know:

• Lifetime: neither Service Keys nor private app tokens expire on their own. Service Keys can be rotated with a 7-day grace period during which both the old and new key work - useful for zero-downtime rotation.
• Scope: a key or token can only be granted scopes the creating user already holds, and is limited to exactly the scopes selected at creation. Add more later from the same settings page if your integration grows.
• Ownership: Service Keys are account-level - they keep working even if the person who created them leaves the account. Admins retain access to manage and rotate them.
• Revocation: rename, rotate, or delete a Service Key from Settings → Integrations → Service Keys; revoke a private app token by deleting the private app under Settings → Integrations → Private Apps.

If you're building for multiple HubSpot accounts (OAuth)

Service Keys and private apps are both single-account credentials. If you're distributing an integration that connects to other people's HubSpot accounts - a Marketplace app or a multi-tenant product - you need OAuth 2.0 via a project-based app built with the HubSpot CLI, not a Service Key or private app token (HubSpot Developer Blog, HubSpot Service Keys).

Minimal working example

This calls /crm/v3/objects/contacts with a limit of 1 — a good smoke test that confirms your token and scopes work.

curl:

curl "https://api.hubapi.com/crm/v3/objects/contacts?limit=1" \
  -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN"

Node.js:

const res = await fetch(
  "https://api.hubapi.com/crm/v3/objects/contacts?limit=1",
  {
    headers: {
      Authorization: `Bearer ${process.env.HUBSPOT_ACCESS_TOKEN}`,
    },
  }
);

console.log(await res.json());

Store HUBSPOT_ACCESS_TOKEN as an environment variable - never hard-code a Service Key or private app token in source control.

Common errors and fixes

Why am I getting 401 INVALID_AUTHENTICATION?

‍The token is missing, malformed, or has been deleted/rotated on HubSpot's side. Confirm the Authorization header is exactly Bearer <token> (with the space after "Bearer"), and that you're using the current key - if you recently rotated a Service Key, update every integration that referenced the old one before its grace period ends.

Why am I getting 403 with a scopes-related message?

‍Your Service Key or private app doesn't have the scope the endpoint requires (e.g., calling a deals endpoint without crm.objects.deals.read). Add the missing scope from Settings → Integrations → Service Keys (or the private app's Scopes tab), save, and re-copy the token if prompted.

Why am I getting 429 with errorType: "RATE_LIMIT"?

‍You've exceeded either a per-second or daily limit. The response body's policyName field says which (SECONDLY or DAILY), and response headers X-HubSpot-RateLimit-Remaining (burst, scoped to the window in X-HubSpot-RateLimit-Interval-Milliseconds) and X-HubSpot-RateLimit-Daily-Remaining show what's left. The older X-HubSpot-RateLimit-Secondly-Remaining header is still present but deprecated and no longer enforced (HubSpot Developers, API usage guidelines and limits).

The faster way

Choosing between Service Keys, private apps, and OAuth, then mapping scopes and watching per-second and daily limits works fine for one HubSpot account. It gets more involved once you're connecting HubSpot alongside other CRMs — each with its own auth model and object schema. Knit's unified CRM API handles HubSpot's auth and rate-limit backoff for you, and normalizes contacts, companies, and deals alongside connectors like Salesforce behind one schema. See the HubSpot API overview for what's available, or book a demo to see it against your own account. You can also sign up free and connect a sandbox HubSpot account.

FAQ

Does HubSpot still have "API keys"?

‍Not in the old sense - HubSpot retired its legacy static API keys (the ones passed as a hapikey query parameter) in November 2022. If you see a tutorial referencing ?hapikey=..., it no longer works. Today, "API key" searches usually mean a Service Key or a private app access token, both sent as Authorization: Bearer <token>.

What's the difference between a Service Key and a private app access token?

‍A Service Key is a newer (2026), account-level credential built specifically for data-only, system-to-system integrations - it's simple to create in Settings and supports clean rotation, but doesn't support webhooks. A private app access token is the older mechanism, also a Bearer token, but tied to a private app that can use webhooks and UI extensions. If you only need to read/write CRM data, HubSpot recommends Service Keys; if you need webhooks, use a private app or project-based app.

How do I authenticate to the HubSpot API?

‍Send your Service Key or private app access token as Authorization: Bearer <token> on every request to api.hubapi.com. There's no separate signing step or token exchange for either credential type - the token you copy from Settings is the token you use.

What scopes do I need for my HubSpot integration?

‍It depends on the objects you're working with - for example, crm.objects.contacts.read and .write for contacts, crm.objects.deals.read/.write for deals, and similar per-object scopes for companies and tickets. Both Service Keys and private apps let you select scopes individually at creation and add more later; grant only what your integration actually uses.

What happens if I exceed HubSpot's API rate limits?

‍HubSpot returns 429 with a JSON body containing errorType: "RATE_LIMIT" and a policyName of either SECONDLY (burst limit) or DAILY (daily cap). Response headers X-HubSpot-RateLimit-Remaining and X-HubSpot-RateLimit-Daily-Remaining let you check usage before hitting the limit (the older X-HubSpot-RateLimit-Secondly-Remaining header still appears but is deprecated). Knit handles this backoff automatically across the HubSpot connections it manages.

‍

‍

The Zendesk Ticketing API (part of Zendesk's Support API, under /api/v2/) is the REST interface for managing tickets, users, organizations, and views in a Zendesk account. It authenticates with an API token (Basic auth) or an OAuth access token (Bearer), returns JSON, and is rate-limited per minute based on your Zendesk plan.

This page covers how authentication works, the endpoints and objects you'll use most, rate limits and pagination, and where Knit's unified API fits if you're connecting Zendesk alongside other ticketing tools.

Authentication

Zendesk supports two authentication methods: API tokens, sent as Basic auth using {email}/token:{api_token}, and OAuth access tokens, sent as Authorization: Bearer <access_token>. API token access must be explicitly enabled by an admin before tokens work, and OAuth is required if you're distributing an integration to multiple Zendesk accounts (Zendesk Developer Docs, Security and authentication).

For the full walkthrough - enabling token access, generating a token, and a working curl example - see How to Get a Zendesk API Token.

Core objects and endpoints

Common tasks

• Create a ticket: POST /api/v2/tickets.json with a ticket object containing subject, comment.body, and a requester (email or ID).
• Update a ticket: PUT /api/v2/tickets/{id}.json with the fields to change, such as status or priority - note the 30-updates-per-10-minutes-per-agent limit on this endpoint.
• List or search tickets: GET /api/v2/search.json?query=type:ticket status:open for filtered results, or GET /api/v2/tickets.json for all tickets with pagination.
• Read a ticket's conversation: GET /api/v2/tickets/{id}/comments.json returns the public and internal comments on a ticket in order.
• Bulk-sync changed records: use the incremental export endpoints (/api/v2/incremental/tickets/cursor.json, etc.) to pull everything changed since a given timestamp - the recommended approach for keeping an external system in sync.

Rate limits and pagination

Zendesk's Support and Help Center API rate limits depend on your plan, documented at developer.zendesk.com/api-reference/introduction/rate-limits:

Every response includes X-Rate-Limit and X-Rate-Limit-Remaining headers (Ticketing endpoints also add ratelimit-limit, ratelimit-remaining, and ratelimit-reset). Exceeding the limit returns 429 Too Many Requests with a Retry-After header. Some endpoints carry their own tighter limits regardless of plan - for example, the Update Ticket endpoint allows only 30 updates to the same ticket by the same agent within 10 minutes, and incremental export endpoints are capped at 10 requests/minute (30 with the High Volume add-on).

For pagination, Zendesk recommends cursor pagination: pass page[size] (max 100) and follow links.next until meta.has_more is false. The older offset pagination (page=N&per_page=...) is capped at the first 100 pages / 10,000 records - requests beyond that return 400 Bad Request (Zendesk Developer Docs, Pagination).

Build it yourself vs. use a unified API

Calling the Zendesk API directly works well for a single account: enable token access, handle the Basic-auth encoding, and watch the per-minute and per-endpoint rate limits. It gets more involved once you're connecting Zendesk alongside other ticketing systems - each with its own auth scheme, object model, and pagination style.

Knit's unified Ticketing API normalizes Zendesk tickets, users, and comments alongside connectors like Freshdesk, Intercom, and Jira behind one schema, handles the token/OAuth setup described in the Zendesk API token guide, and manages rate-limit backoff for you. See Knit's Zendesk Ticketing connector for what's available, or book a demo to see it against your own account. You can also sign up free and connect a sandbox Zendesk account.

FAQ

Is the Zendesk Ticketing API a REST API?

‍Yes - it follows REST conventions under /api/v2/, using GET, POST, PUT, and DELETE on resource URLs with JSON bodies. It's part of Zendesk's broader Support API, which also includes the Help Center API (separate rate limit) and Side Conversations API.

How do I authenticate to the Zendesk Ticketing API?

‍Use either an API token with Basic auth ({email}/token:{api_token}, base64-encoded) or an OAuth access token sent as Authorization: Bearer <token>. API token access must be turned on by an admin in Admin Center before tokens work. See the Zendesk API token guide for setup steps.

How do I sync all my Zendesk tickets into another system?

‍Use the incremental export endpoints (/api/v2/incremental/tickets/cursor.json and equivalents for users and organizations), which return everything changed since a given timestamp using cursor-based pagination — designed for bulk sync rather than one-off queries. These endpoints have their own tighter rate limit (10/minute, or 30/minute with the High Volume add-on). Knit's unified API exposes equivalent sync primitives across ticketing connectors without needing endpoint-specific incremental-export logic.

What happens if I exceed Zendesk's API rate limits?

‍Zendesk returns 429 Too Many Requests with a Retry-After header specifying how many seconds to wait. The X-Rate-Limit and X-Rate-Limit-Remaining headers on every response let you monitor usage before hitting the limit. Limits range from 200 to 2,500 requests/minute depending on your plan, and some endpoints (like ticket updates) have their own separate caps. Knit handles this backoff automatically across the Zendesk connections it manages.

To get a Zendesk API token, an admin first enables API access in Admin Center → Apps and integrations → APIs → API configuration (accept the terms, then turn on Allow API token access), then generates a token under APIs → API tokens → Add API token. Use the token with Basic auth: base64-encode {email_address}/token:{api_token} and send it in the Authorization header.

The rest of this page covers where the credential goes, a working code sample, and the errors you'll hit if token access isn't enabled or the format is wrong.

Prerequisites

Administrator access to your Zendesk account's Admin Center - only admins can turn on API token access and generate tokens (source: Zendesk Help, Managing API token access to the Zendesk API).

A verified user (email address) on the account - API tokens are used alongside a verified user's email, not on their own.

A decision on whether an API token (simple, account-wide Basic auth) or an OAuth access token (scoped to an OAuth client, supports CORS) fits your integration (source: Zendesk Developer Docs, Security and authentication)

Step-by-step: creating a Zendesk API token

1. In Admin Center, click Apps and integrations in the sidebar, then go to APIs → API configuration.
2. Accept the Zendesk Terms of Service and Application Developer and API Agreement, then check Allow API token access and click Save (Zendesk Help, Turning on and off API access).
3. Still under Apps and integrations, go to APIs → API tokens.
4. Click Add API token, optionally enter a description, then click Save.
5. Copy the token immediately — once you close this dialog, the full token is never shown again; only a truncated version is visible afterward (Zendesk Help, Managing API token access to the Zendesk API).
6. Store the token alongside the email address of a verified user — both are required to authenticate.

‍

Where the credential goes

Zendesk API tokens use Basic authentication, combined with a verified user's email address. Build the credential string as:

{email_address}/token:{api_token}

Base64-encode that string and send it in the Authorization header:

Authorization: Basic <base64-encoded {email}/token:{api_token}>

With curl, you can skip the manual encoding by passing -u:

curl https://yoursubdomain.zendesk.com/api/v2/users/me.json \
  -u jdoe@example.com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv

(Zendesk Developer Docs, Security and authentication)

Connector-specific gotcha: API token access is off by default at the account level. If you generate a token under APIs → API tokens before enabling Allow API token access in API configuration, every request authenticated with that token returns 401 Unauthorized - The token itself is valid, but the account isn't accepting token-based auth yet. If your brand-new token doesn't work, check the API configuration toggle first, not the token.

A few other things to know:

• Lifetime: API tokens don't expire on their own. They remain valid until an admin deactivates and deletes them. You can have up to 256 active tokens (existing accounts that already exceed this have a cap of 2,048).
• Scope: an API token isn't tied to a single user - it's account-wide. Any verified user's email can be paired with any active token to authenticate, and the resulting request has that user's permissions. Treat tokens like shared admin passwords.
• Revocation: deactivate the token from APIs → API tokens (this immediately breaks any requests using it), then delete it once you've confirmed nothing else depends on it. A token must be deactivated before it can be deleted.

If you need OAuth instead (scoped, per-app access)

If you're distributing an integration to multiple Zendesk accounts, or want CORS-friendly browser requests and tokens scoped to a specific OAuth client, use an OAuth access token instead. Create an OAuth client in Admin Center, run the authorization flow, and send the resulting token as:

Authorization: Bearer <access_token>

OAuth access tokens can be up to 184 characters and are scoped to the Zendesk instance whose OAuth client issued them (Zendesk Developer Docs, Security and authentication).

Minimal working example

This calls /api/v2/users/me.json, which returns the authenticated user's profile — a good smoke test for a new token.

curl:

curl "https://$ZENDESK_SUBDOMAIN.zendesk.com/api/v2/users/me.json" \
  -u "$ZENDESK_EMAIL/token:$ZENDESK_API_TOKEN"

Node.js:

const credentials = Buffer.from(
  `${process.env.ZENDESK_EMAIL}/token:${process.env.ZENDESK_API_TOKEN}`
).toString("base64");

const res = await fetch(
  `https://${process.env.ZENDESK_SUBDOMAIN}.zendesk.com/api/v2/users/me.json`,
  {
    headers: {
      Authorization: `Basic ${credentials}`,
    },
  }
);

console.log(await res.json());

Store ZENDESK_SUBDOMAIN, ZENDESK_EMAIL, and ZENDESK_API_TOKEN as environment variables — never hard-code the token or commit it to source control.

Common errors and fixes

Why am I getting 401 Unauthorized with a valid token?

‍The most common cause is that Allow API token access isn't enabled in Admin Center → Apps and integrations → APIs → API configuration. Enable it, save, and retry. Also double-check the credential format — it's {email}/token:{api_token}, including the literal /token, not just the email and token separated by a colon (Zendesk Help, Turning on and off API access).

Why am I getting 403 Forbidden?

‍The token is valid and account-wide, but the user whose email you paired it with doesn't have permission for that endpoint — for example, a non-admin agent calling an admin-only endpoint. Pair the token with a user (or admin) that has the right role for the resource you're calling.

Why am I getting 429 Too Many Requests?

‍You've exceeded your plan's API rate limit (200–2,500 requests per minute depending on plan, or lower for specific endpoints). The response includes a Retry-After header telling you how many seconds to wait, and X-Rate-Limit / X-Rate-Limit-Remaining headers show your limit and remaining quota for the current minute (Zendesk Developer Docs, Rate limits).

The faster way

Enabling token access, generating a token, and getting the Basic auth encoding right works fine for one Zendesk account. It gets more involved once you're connecting Zendesk alongside other ticketing tools — each with its own auth scheme, object model, and rate-limit shape. Knit's unified Ticketing API normalizes Zendesk alongside connectors like Freshdesk and Intercom behind one schema, handles token storage, and manages rate-limit backoff for you. See the Zendesk Ticketing API overview for what's available, or book a demo to see it against your own account. You can also sign up free and connect a sandbox Zendesk account.

FAQ

Where do I generate a Zendesk API token?

‍In Admin Center, go to Apps and integrations → APIs → API tokens and click Add API token. Before this works, an admin must first enable Allow API token access under APIs → API configuration. Copy the token immediately after creating it - Zendesk only shows the full value once.

Why does my Zendesk API request return 401 even though my token is correct?

‍Almost always because Allow API token access hasn't been turned on in API configuration, or because the Authorization header isn't formatted as {email}/token:{api_token} (base64-encoded for the header, or passed via -u in curl). Both the toggle and the format need to be correct.

Is a Zendesk API token tied to one user?

‍No. An API token is account-wide - it's an auto-generated password that can be combined with any verified user's email address. The permissions on a given request come from whichever user's email you paired with the token, not from the token itself. Because of this, Zendesk recommends treating tokens like shared admin passwords and deleting any you're not using.

Should I use an API token or OAuth for my Zendesk integration?

‍API tokens are simplest for a single account and internal tools. Use OAuth access tokens if you're building something distributed to multiple Zendesk accounts (Zendesk's developer terms require global OAuth tokens for that case), or if you need CORS-friendly browser requests and per-client scoping. Knit's Zendesk connector handles the OAuth flow for you if you connect via Knit.

What are Zendesk's API rate limits?

‍They depend on your plan: roughly 200 requests/minute on Team, 400 on Growth/Professional, 700 on Enterprise, and up to 2,500 on Enterprise Plus or with the High Volume API add-on. Some endpoints have their own tighter limits - for example, updating the same ticket is capped at 30 times per 10 minutes per agent. Knit manages this backoff automatically across the Zendesk connections it handles.

Salesforce doesn't issue a single "API key" - instead you create a Connected App in Setup, enable OAuth settings, and get a Consumer Key (client ID) and Consumer Secret (client secret). You exchange those for an OAuth 2.0 access token - using the Client Credentials flow for server-to-server integrations, or the Web Server (Authorization Code) flow for per-user access - and send that token as Authorization: Bearer <token> on REST API calls.

The rest of this page covers the setup steps, where the credential goes, a working code sample, and the errors you'll hit if something's misconfigured.

Prerequisites

• A Salesforce org where you can create Connected Apps — this requires the "Customize Application" and "Manage Connected Apps" permissions, typically held by System Administrators.
• A My Domain configured for your org. Salesforce requires My Domain to be enabled before OAuth flows work (Salesforce Help, Enable OAuth Settings for API Integration).
• A decision on which OAuth flow fits: Client Credentials for a server-to-server integration with no end user, or Web Server (Authorization Code) if the integration needs to act as a specific Salesforce user.

Step-by-step: creating a Salesforce Connected App and getting your Consumer Key

1. In Setup, enter "App Manager" in the Quick Find box, then click New Connected App.
2. Fill in the Connected App Name, API Name (auto-filled), and a contact Email.
3. Under API (Enable OAuth Settings), check Enable OAuth Settings. Enter a Callback URL - Salesforce requires one even for server-to-server flows; a placeholder URL works if you won't use a redirect-based flow.
4. Add OAuth Scopes. At minimum, add "Manage user data via APIs (api)". If your integration needs long-lived access without re-prompting a user, also add "Perform requests at any time (refresh_token, offline_access)" (Salesforce Help, Enable OAuth Settings for API Integration).
5. For server-to-server integrations, also enable Client Credentials Flow under the connected app's policies and assign a "Run As" user — this user's permissions determine what the integration can access (Salesforce Help, Configure a Connected App for the OAuth 2.0 Client Credentials Flow).
6. Click Save. Salesforce can take up to 10 minutes to propagate a new Connected App - if your first token request fails, wait and retry.
7. Open the app and click Manage Consumer Details. Salesforce emails a verification code to confirm your identity; enter it, then copy the Consumer Key and Consumer Secret.

Where the credential goes

The Consumer Key and Consumer Secret aren't sent directly on API calls - they're exchanged for an OAuth access token at your org's token endpoint:

POST https://login.salesforce.com/services/oauth2/token

For the Client Credentials flow, send grant_type=client_credentials with your client_id (Consumer Key) and client_secret (Consumer Secret). The response includes an access_token and an instance_url. Use the token on subsequent calls:

Authorization: Bearer <access_token>

against <instance_url>/services/data/v66.0/... (Salesforce Developers, Authorization Through Connected Apps and OAuth 2.0).

Connector-specific gotcha: the instance_url returned in the token response is specific to your org (e.g., https://yourcompany.my.salesforce.com) and can change — for example, after a sandbox refresh or org migration. Always use the instance_url from the most recent token response for your API calls rather than hardcoding a domain; a cached or assumed domain is a common source of IP_RESTRICTED or connection errors after a sandbox refresh.

A few other things to know:

• Lifetime: access tokens are session-based and expire according to your org's session timeout policy (2 hours by default, but configurable in Setup). Client Credentials flow tokens are not paired with a refresh token — request a new one when the current one expires or returns INVALID_SESSION_ID.
• Refresh: if you used the Web Server (Authorization Code) flow with the refresh_token and offline_access scopes, exchange the refresh token at the same /services/oauth2/token endpoint with grant_type=refresh_token to get a new access token without re-prompting the user.
• Scopes: api covers REST, SOAP, Bulk, and Metadata API access for the Run As user's permission set — grant the Run As user only the object and field permissions the integration needs, since the scope itself doesn't restrict data access beyond that user's profile.
• Revocation: revoke a Connected App's access from Setup → Apps → Connected Apps OAuth Usage, or from the integration user's own Connected Apps list under personal settings.

If you need per-user access instead (Authorization Code flow)

If your integration needs to act on behalf of different Salesforce users (not a single Run As user), use the Web Server (Authorization Code) flow: direct the user to https://login.salesforce.com/services/oauth2/authorize?response_type=code&client_id=...&redirect_uri=..., then exchange the returned code at /services/oauth2/token with grant_type=authorization_code for an access token and refresh token (Salesforce Developers, Authorization Through Connected Apps and OAuth 2.0).

Minimal working example

This uses the Client Credentials flow to get a token, then calls the REST API's limits endpoint — a good smoke test that doesn't depend on any specific object data.

curl:

# 1. Get an access token
curl -X POST https://login.salesforce.com/services/oauth2/token \
  -d "grant_type=client_credentials" \
  -d "client_id=$SF_CONSUMER_KEY" \
  -d "client_secret=$SF_CONSUMER_SECRET"

# Response includes "access_token" and "instance_url" — use both below

# 2. Call the REST API
curl "$SF_INSTANCE_URL/services/data/v66.0/limits" \
  -H "Authorization: Bearer $SF_ACCESS_TOKEN"

Node.js:

const tokenRes = await fetch("https://login.salesforce.com/services/oauth2/token", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "client_credentials",
    client_id: process.env.SF_CONSUMER_KEY,
    client_secret: process.env.SF_CONSUMER_SECRET,
  }),
});
const { access_token, instance_url } = await tokenRes.json();

const res = await fetch(`${instance_url}/services/data/v66.0/limits`, {
  headers: { Authorization: `Bearer ${access_token}` },
});
console.log(await res.json());

Store SF_CONSUMER_KEY and SF_CONSUMER_SECRET as environment variables, and treat the resulting access token as a short-lived secret too.

Common errors and fixes

Why am I getting invalid_client_id or invalid_client?

‍Either the Consumer Key/Secret is wrong, or the Connected App hasn't finished propagating yet - Salesforce can take up to 10 minutes after creation or after enabling Client Credentials Flow. Double-check you copied the Consumer Key and Secret from Manage Consumer Details, and retry after a few minutes (Salesforce Help, Configure a Connected App for the OAuth 2.0 Client Credentials Flow).

Why am I getting a 401 with INVALID_SESSION_ID?

‍Your access token expired or was revoked - session-based tokens expire per your org's session timeout policy (2 hours by default). Request a new access token via the same OAuth flow; if you're using the Authorization Code flow with offline_access, use the refresh token instead of restarting the full flow (Salesforce Developers, Authorization Through Connected Apps and OAuth 2.0).

Why am I getting a 403 with REQUEST_LIMIT_EXCEEDED?

‍Your org has exceeded its Daily API Request Limit (100,000 requests per rolling 24 hours for Enterprise Edition, plus 1,000 per additional user license, scaling with org size). This is a soft limit that allows temporary bursts, but a hard cap blocks further calls until usage drops back under the limit. Check current usage via the Sforce-Limit-Info response header or the /services/data/vXX.0/limits endpoint (Salesforce Developers Blog, API Limits and Monitoring Your API Usage).

The faster way

Setting up a Connected App, choosing the right OAuth flow, and tracking the instance_url and daily limits works fine for one Salesforce org. It gets harder once you're connecting Salesforce alongside other CRMs — each with different auth flows, object models, and rate-limit shapes. Knit's unified CRM API handles Salesforce's OAuth and instance_url routing, normalizes object data across connectors, and manages rate-limit backoff for you. See the Salesforce API overview for what's available, or book a demo to see it against your own org. You can also sign up free and connect a sandbox Salesforce org in a few minutes.

FAQ

Where do I find my Salesforce Consumer Key and Consumer Secret?

‍After creating a Connected App in Setup → App Manager, open it and click "Manage Consumer Details." Salesforce sends a verification code to your registered email to confirm your identity before showing the Consumer Key (client ID) and Consumer Secret (client secret). You can return to this page later to view them again.

Does Salesforce have a simple API key like some other platforms?

‍No — Salesforce doesn't issue a static "API key" you paste into a header. Access is always through OAuth 2.0: a Connected App's Consumer Key and Secret are exchanged for a short-lived access token, which is what you actually send with API requests. This adds setup steps but means credentials can be rotated and scoped without changing a hardcoded key.

What's the difference between the Client Credentials flow and the Authorization Code flow?

‍The Client Credentials flow is server-to-server: your app exchanges its Consumer Key and Secret directly for a token tied to a configured "Run As" user, with no end-user login. The Authorization Code (Web Server) flow involves a Salesforce user logging in and granting consent, after which your app gets an access token and refresh token tied to that specific user. Use Client Credentials for backend integrations and Authorization Code when the integration needs to act as different individual users.

How long does a Salesforce access token last?

‍It depends on your org's session timeout setting in Setup, which defaults to 2 hours but can be configured higher or lower. There's no fixed "token expiry" separate from session timeout. If you're using the Authorization Code flow with the refresh_token and offline_access scopes, your app can silently get a new access token via the refresh token instead of expiring the user's session.

What are Salesforce's API rate limits?

‍Most paid editions (e.g., Enterprise Edition) get a Daily API Request Limit starting at 100,000 calls per rolling 24-hour period, increasing with the number of user licenses your org has. It's a soft limit - short bursts above it are allowed - but a hard system-protection limit eventually returns 403 REQUEST_LIMIT_EXCEEDED until usage drops back down. Knit manages this backoff automatically across the Salesforce connections it handles.

‍

‍

To get a Jira API token, log in to id.atlassian.com/manage-profile/security/api-tokens, select Create API token (or Create API token with scopes), name it, set an expiration of up to 365 days, and copy the value immediately — it's shown only once. Use that token as the password in HTTP Basic Auth, paired with your Atlassian account email, to call the Jira Cloud REST API.

The rest of this page covers scoped vs. unscoped tokens, where the credential goes on a request, a working code sample, and the errors you'll hit if something's misconfigured.

Prerequisites

• An Atlassian account with access to the Jira Cloud site you want to call (https://your-domain.atlassian.net).
• Two-step verification or SSO doesn't block token creation, but if you log in with a password or third-party login, Atlassian emails you a one-time passcode to verify your identity before you can create or manage tokens (Atlassian Support, Manage API tokens).
• If you need an app to act on behalf of other users (not just your own account), you want OAuth 2.0 (3LO) instead — see the note near the bottom of this page.

Step-by-step: creating a Jira API token

1. Log in to id.atlassian.com/manage-profile/security/api-tokens.
2. Select Create API token with scopes (recommended) or Create API token for an unscoped token.
3. Give the token a name that describes what it's for, e.g. "jira-sync-prod".
4. Set an expiration date — anywhere from 1 to 365 days. New tokens default to a 1-year expiry. If you have an old token created before December 15, 2024 that you haven't replaced yet, it has already expired — Atlassian transitioned all pre-Dec-2024 tokens to expire between March 14 and May 12, 2026, and that window has passed (Atlassian Support, Manage API tokens).
5. If you chose scopes, pick Jira as the app and select the scopes the integration needs — for example read:jira-work for read-only access or write:jira-work to also create and update issues (Atlassian Support, Manage API tokens).
6. Select Create, then Copy to clipboard and store the token in a secrets manager or environment variable. Atlassian cannot show it to you again — if you lose it, revoke it and create a new one.

Where the credential goes

Jira Cloud's REST API uses HTTP Basic Authentication, with your Atlassian account email as the username and the API token as the password (Atlassian Developer, Basic auth for REST APIs):

Authorization: Basic base64(email:api_token)

Most HTTP clients build this for you — with curl, pass -u email@example.com:api_token.

Connector-specific gotcha: if you created an API token with scopes, requests must go to api.atlassian.com/ex/jira/{cloudId}/..., not your normal https://your-domain.atlassian.net/... base URL. Unscoped (legacy) tokens still work against your-domain.atlassian.net, but scoped tokens are routed through Atlassian's gateway using your site's cloudId (Atlassian Support, Manage API tokens).

A few other things to know:

• Lifetime: 1–365 days, set at creation. There's no separate "refresh" — when a token expires, you generate a new one and update wherever it's stored.
• Scopes: prefer scoped tokens with the narrowest scope that works (read:jira-work if you're only reading issues). Unscoped tokens inherit the full permission set of the account that created them.
• Revocation: revoke a token any time from the same API tokens page — it stops working immediately and can't be recovered.

If you need OAuth 2.0 (3LO) instead

If your integration needs to act on behalf of multiple Jira users (not just your own account), use OAuth 2.0 (3LO): register an app in the Atlassian developer console, enable OAuth 2.0 (3LO) under Authorization, then direct users through https://auth.atlassian.com/authorize to get an authorization code, and exchange it at https://auth.atlassian.com/oauth/token for an access token and (with the offline_access scope) a rotating refresh token (Atlassian Developer, OAuth 2.0 (3LO) apps). Refresh tokens expire after 90 days of inactivity, and each use issues a new refresh token that replaces the old one.

Minimal working example

This calls GET /rest/api/3/myself, which returns the profile of the authenticated user — a good smoke test for a new token.

curl:

curl -X GET \
  -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -H "Accept: application/json" \
  "https://$JIRA_DOMAIN.atlassian.net/rest/api/3/myself"

Node.js:

const auth = Buffer.from(
  `${process.env.JIRA_EMAIL}:${process.env.JIRA_API_TOKEN}`
).toString("base64");

const res = await fetch(
  `https://${process.env.JIRA_DOMAIN}.atlassian.net/rest/api/3/myself`,
  {
    headers: {
      Authorization: `Basic ${auth}`,
      Accept: "application/json",
    },
  }
);

const data = await res.json();
console.log(data.displayName);

Store JIRA_EMAIL, JIRA_API_TOKEN, and JIRA_DOMAIN as environment variables — never hard-code the token.

Common errors and fixes

Why am I getting a 401 Unauthorized?

‍Either the email/token pair is wrong, the token has expired, or it was revoked. Regenerate a token from id.atlassian.com/manage-profile/security/api-tokens and confirm you're using the Atlassian account email, not a username, as the Basic Auth username (Atlassian Developer, Basic auth for REST APIs).

Why does my request fail with an X-Seraph-LoginReason: AUTHENTICATION_DENIED header?

‍Jira triggers a CAPTCHA after several consecutive failed logins, and the REST API can't complete a CAPTCHA challenge. This header means the login was rejected before the password was even checked. Log in to the Jira web UI once to clear the CAPTCHA, then retry the API call (Atlassian Developer, Basic auth for REST APIs).

Why does refreshing my OAuth token return 403 invalid_grant?

‍This means the refresh token is unknown or invalid — usually because the user changed their Atlassian password, the refresh token expired after 90 days of inactivity, or your app didn't store the new rotating refresh token from the previous exchange. If it's expired, the user needs to redo the full authorization flow (Atlassian Developer, OAuth 2.0 (3LO) apps).

The faster way

Generating and rotating a Jira API token works fine for one integration. It gets harder once you're connecting Jira alongside other ticketing tools — each with its own token formats, scoped-vs-unscoped routing quirks, and refresh schedules. Knit's unified ticketing API handles Jira's auth (including the scoped-token cloudId routing above), normalizes issue and project data across connectors, and refreshes credentials automatically. See the Jira API overview for what's available, or book a demo to see it against your own Jira site. You can also sign up free and connect a sandbox Jira instance in a few minutes.

FAQ

Where do I find my Jira API token after creating it?

‍Atlassian shows the token value only once, immediately after you click "Create." Copy it then — if you lose it, revoke the old token and create a new one. Existing tokens (without their values) are listed at id.atlassian.com/manage-profile/security/api-tokens, where you can see names, expiration dates, and scopes.

What's the difference between a Jira API token and OAuth 2.0 (3LO)?

‍An API token authenticates as you via Basic Auth — simple, but tied to one Atlassian account. OAuth 2.0 (3LO) lets an app act on behalf of other users after they grant consent through an authorization screen, and issues short-lived access tokens plus rotating refresh tokens. Use a token for personal scripts and internal automation; use OAuth 2.0 (3LO) for an app that multiple Jira users will install.

Do Jira API tokens expire?

‍Yes. New tokens expire 1–365 days after creation, whichever date you set (1-year default). Tokens created before December 15, 2024 were transitioned under Atlassian's policy change and have already expired as of May 2026 — if you're still relying on one of those, generate a replacement now. There's no auto-renewal otherwise — generate a new token before the current one expires and update it wherever it's stored.

Why do I need my site's cloudId for some Jira API calls?

‍Scoped API tokens and OAuth 2.0 (3LO) apps both call the Jira API through api.atlassian.com/ex/jira/{cloudId}/... rather than your-domain.atlassian.net. Get the cloudId by calling GET https://api.atlassian.com/oauth/token/accessible-resources (for OAuth) — for scoped API tokens, the same gateway pattern applies using your site's cloud ID.

Is the Jira API free to use with an API token?

‍Yes — creating a token and calling the Jira Cloud REST API costs nothing beyond your existing Atlassian subscription. Usage is governed by Jira's rate limits: a 65,000-points-per-hour global quota shared across apps, plus per-endpoint burst limits (typically 100 GET requests/second). API token-based traffic continues to be governed by the existing burst limits rather than the newer points-based quota.

Last verified: 2026-06-13 against the sources listed below.

Sources:

• Manage API tokens for your Atlassian account — Atlassian Support
• Basic auth for REST APIs — Atlassian Developer
• OAuth 2.0 (3LO) apps — Atlassian Developer
• Rate limiting — Atlassian Developer

‍

‍Slack has four API surfaces — Web API, Events API, Incoming Webhooks, and Socket Mode — and picking the wrong one is the most common reason Slack integrations need to be rebuilt. This guide explains what each surface does, which one your integration actually needs, and how to work with the key Web API endpoints (chat.postMessage, chat.update, conversations.list, users.lookupByEmail) with real code examples.

Quick answer: For most product integrations — sending notifications, DMs, interactive messages, slash commands — use the Web API with a bot token. Use the Events API when you need Slack to push events to your server in real time. Use Incoming Webhooks only for simple, one-way alerts to a fixed channel.

If you've ever searched "how to integrate with Slack," you've probably landed on a page that explains how to post a message using an Incoming Webhook — and wondered why there are three other APIs that seem to do something similar.

That confusion is real, and it costs engineering teams time. Slack has four distinct API surfaces: the Web API, the Events API, Incoming Webhooks, and Socket Mode. Each one exists for a different reason. Picking the wrong one means either building something that breaks when Slack's terms change, or over-engineering a simple notification system.

This guide cuts through that. By the end, you'll know exactly which Slack API surface your integration needs, how OAuth works, how the key endpoints behave, and how to handle slash commands and interactive messages. There's also a section on building via Knit, if you'd rather skip managing Slack auth and token lifecycle yourself and if you plan to add a ms teams integration later as it solves for  both in one go.

‍

The Four Slack API Surfaces

1. Web API

The Slack Web API is a standard HTTPS REST API. You make requests to https://slack.com/api/{method}, pass a bot token in the Authorization header, and get JSON back. It is the foundation of most serious Slack integrations — over 100 methods are available covering messaging, user management, channels, files, and more.

Use it when you need to initiate actions from your server: send messages, look up users, list channels, update a message after it's been sent, or respond to interactions.

2. Events API

The Events API flips the direction. Instead of your server calling Slack, Slack calls your server via HTTP POST whenever something happens — a message is posted, a user joins a channel, a reaction is added, and so on. You register a public URL, Slack sends events to it, and you process them.

Use it when your integration needs to react to things happening in Slack: syncing messages to an external system, triggering workflows when users mention a keyword, or logging activity.

3. Incoming Webhooks

Incoming Webhooks are the simplest option. During app installation, Slack gives you a URL. You POST JSON to that URL and a message appears in a pre-configured channel. There's no OAuth flow to manage at runtime, no tokens to refresh — just one URL.

Use them when you want to push simple notifications from an external system into a single channel: CI/CD build alerts, server monitoring notifications, daily digest messages.

The constraint: each webhook is tied to one channel at install time. You can't dynamically choose where to send the message, and you can't read data or respond to events.

4. Socket Mode

Socket Mode lets your app receive events over a persistent WebSocket connection rather than an HTTP endpoint. This means Slack doesn't need to reach a public URL — useful during development, or when your app runs behind a firewall or in an environment where exposing a port isn't possible.

Use it for local development or for apps that live in environments without a public-facing URL. In production, the Events API is generally preferred.

Authentication: OAuth 2.0 for Slack Apps

Creating a Slack App

Start at api.slack.com/apps. Create a new app, either from scratch or from an app manifest. An app manifest is a YAML or JSON file that declares your app's permissions, event subscriptions, and slash commands — useful for version-controlling your app configuration.

Bot Tokens vs User Tokens

When your app is installed to a workspace, Slack issues two types of tokens:

• Bot token (xoxb-...): Acts on behalf of your app's bot user. This is what most integrations use. The bot can only access channels it's been added to.
• User token (xoxp-...): Acts on behalf of the user who installed the app. Has access to that user's data. Generally only needed if your integration requires user-level permissions (e.g., reading someone's private messages on their behalf).

For the full step-by-step on generating a bot token — including where to find it after install and the most common missing_scope fix — see How to Get a Slack Bot Token.

For most integration use cases — sending notifications, managing channels, looking up users — a bot token is sufficient and the safer choice.

OAuth Scopes

Scopes define what your app can do. You declare required scopes when creating the app, and users see them listed when installing. Request only what you need — over-permissioned apps create friction at install time.

Common scopes for a messaging integration:

‍

The OAuth Install Flow

1. Direct the user to Slack's authorization URL with your client_id, requested scopes, and a redirect_uri.
2. User approves the app and is redirected back to your redirect_uri with a temporary code.
3. Your server exchanges the code for an access token via https://slack.com/api/oauth.v2.access.
4. Store the access_token (and team_id) securely. This token doesn't expire — but users can revoke it, and you should handle token_revoked events.

Working with the Slack Web API

All Web API calls follow the same pattern:

POST https://slack.com/api/{method}
Authorization: Bearer xoxb-your-bot-token
Content-Type: application/json

Every response includes an "ok" boolean. If "ok": false, the "error" field tells you why.

{ "ok": false, "error": "channel_not_found" }

Always check ok before using the response body.

Sending Messages: chat.postMessage

The workhorse of most Slack integrations. Sends a message to a channel — or a DM when you pass a user ID as the channel.

POST https://slack.com/api/chat.postMessage
Authorization: Bearer xoxb-your-bot-token
Content-Type: application/json

{
  "channel": "C0123456789",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*New order received* 🎉\nOrder #1042 from Acme Corp — $4,200"
      }
    }
  ]
}

Response:

{
  "ok": true,
  "ts": "1715000000.000100",
  "channel": "C0123456789"
}

Save the ts (timestamp) and channel from the response. Together, these uniquely identify the message and are required to update it later.

The blocks array uses Slack's Block Kit — a structured layout system that lets you build rich messages with sections, buttons, images, and dropdowns. Plain text is also accepted but blocks give you far more control.

Updating Messages: chat.update

When a status changes — a build completes, an order ships, an approval is actioned — update the original message rather than posting a new one. This keeps channels clean.

{
  "channel": "C0123456789",
  "ts": "1715000000.000100",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*Order #1042 — Shipped* ✅\nTracking: UPS 1Z999AA10123456784"
      }
    }
  ]
}

Pass "as_user": true if you want the update to appear as coming from the user rather than the bot.

Listing Channels: conversations.list

Retrieves public and private channels. Useful for letting users select a channel in your app's UI without hardcoding channel IDs.

GET https://slack.com/api/conversations.list?types=public_channel,private_channel&limit=200
Authorization: Bearer xoxb-your-bot-token

{
  "channels": [
    { "id": "C0123456789", "name": "engineering-alerts", "is_private": false },
    { "id": "C0987654321", "name": "finance-approvals", "is_private": true }
  ],
  "response_metadata": {
    "next_cursor": "dGVhbTpDMDYxRkE3OTM="
  }
}

Paginate using the cursor query parameter: pass the next_cursor value from response_metadata as the cursor in your next request. Continue until next_cursor is empty.

Looking Up Users: users.list and users.lookupByEmail

Two options depending on what you have:

users.list — returns all workspace members with pagination. Useful for building a local user cache or populating a dropdown.

GET https://slack.com/api/users.list?limit=200

{
  "members": [
    {
      "id": "U0123456789",
      "is_bot": false,
      "deleted": false,
      "profile": { "email": "sarah@acme.com" }
    }
  ],
  "response_metadata": { "next_cursor": "..." }
}

Filter out bots (is_bot: true) and deactivated users (deleted: true) before storing.

users.lookupByEmail — the faster option when you already know the email. One call, one user.

GET https://slack.com/api/users.lookupByEmail?email=sarah@acme.com

{
  "ok": true,
  "user": { "id": "U0123456789" }
}

Use the returned id directly as the channel in chat.postMessage to send a direct message to that user.

Slash Commands

Slash commands let users trigger actions in your external system by typing /command in any Slack channel. When a user fires one, Slack sends a POST request to your registered endpoint within 3 seconds — if your response takes longer, Slack will show an error.

The Payload

{
  "eventId": "evt_01abc",
  "eventType": "slash_command",
  "eventData": {
    "command": "/report",
    "text": "Q1 2026",
    "keyCommand": "report",
    "argumentCommand": "Q1 2026",
    "userId": "U0123456789",
    "teamId": "T0123456789",
    "channelId": "C0123456789",
    "responseUrl": "https://hooks.slack.com/commands/..."
  }
}

Key fields:

• command — the slash command itself (e.g., /report)
• text — everything the user typed after the command
• keyCommand — the command name without the slash
• argumentCommand — the arguments portion (everything after the command name)
• userId — who triggered it
• responseUrl — a URL you can POST a delayed response to (valid for 30 minutes)

Handling Async Responses

If your command triggers a long-running operation, acknowledge immediately with a simple response, then POST the actual result to responseUrl when ready:

// Immediate acknowledgment (within 3s)
{
  "commandResponse": {
    "text": "Generating your Q1 report, hang tight..."
  }
}

// Delayed response via responseUrl (up to 30 min later)
{
  "commandResponse": {
    "blocks": [
      {
        "type": "section",
        "text": { "type": "mrkdwn", "text": "*Q1 2026 Report*\nRevenue: $2.4M | Growth: +18%" }
      }
    ]
  }
}

Rate Limits

Slack rate-limits the Web API by method, using a tier system:

When you hit a limit, Slack responds with HTTP 429 and a Retry-After header indicating how many seconds to wait. Always implement retry logic with exponential backoff. For high-volume messaging (bulk notifications, digest sends), queue messages and pace them against the per-channel limit.

One gotcha worth flagging: as of a dated change effective May 29, 2025, conversations.history and conversations.replies moved from Tier 3 to Tier 1 (about 1 request/minute, capped at 15 objects per request, down from 1,000) for non-Marketplace, commercially distributed apps created or installed after that date. Marketplace apps and internal apps built for a single workspace are unaffected and keep the higher limits. If your integration suddenly can't paginate channel history at a usable rate, check which category your app falls into.

Three Common Integration Patterns

Pattern 1: Send a DM to a User by Email

A common need: your backend event has a user's email and you need to reach them directly in Slack.

import requests

SLACK_TOKEN = "xoxb-your-bot-token"
HEADERS = {"Authorization": f"Bearer {SLACK_TOKEN}", "Content-Type": "application/json"}

def send_dm_by_email(email: str, message: str):
    # Step 1: Resolve email → user ID
    lookup = requests.get(
        "https://slack.com/api/users.lookupByEmail",
        params={"email": email},
        headers=HEADERS
    ).json()

    if not lookup.get("ok"):
        raise Exception(f"User not found: {lookup.get('error')}")

    user_id = lookup["user"]["id"]

    # Step 2: Send DM (user ID is used as the channel)
    response = requests.post(
        "https://slack.com/api/chat.postMessage",
        headers=HEADERS,
        json={
            "channel": user_id,
            "blocks": [
                {"type": "section", "text": {"type": "mrkdwn", "text": message}}
            ]
        }
    ).json()

    if not response.get("ok"):
        raise Exception(f"Message failed: {response.get('error')}")

    return response["ts"]  # Save for later updates

Pattern 2: Interactive Approval Message

Post a message with Approve/Decline buttons, then update it once the manager acts.

def post_approval_request(channel: str, request_details: str):
    response = requests.post(
        "https://slack.com/api/chat.postMessage",
        headers=HEADERS,
        json={
            "channel": channel,
            "blocks": [
                {
                    "type": "section",
                    "text": {"type": "mrkdwn", "text": f"*Approval Request*\n{request_details}"}
                },
                {
                    "type": "actions",
                    "elements": [
                        {"type": "button", "text": {"type": "plain_text", "text": "✅ Approve"},
                         "action_id": "approve", "style": "primary"},
                        {"type": "button", "text": {"type": "plain_text", "text": "❌ Decline"},
                         "action_id": "decline", "style": "danger"}
                    ]
                }
            ]
        }
    ).json()
    return {"ts": response["ts"], "channel": response["channel"]}


def resolve_approval(ts: str, channel: str, approved: bool, actioned_by: str):
    status = "✅ Approved" if approved else "❌ Declined"
    requests.post(
        "https://slack.com/api/chat.update",
        headers=HEADERS,
        json={
            "channel": channel,
            "ts": ts,
            "blocks": [
                {
                    "type": "section",
                    "text": {"type": "mrkdwn", "text": f"*Approval Request* — {status}\nActioned by: {actioned_by}"}
                }
            ]
        }
    )

Pattern 3: Slash Command Dispatcher

Route different /commands to the right handler in your backend.

from flask import Flask, request, jsonify

app = Flask(__name__)

HANDLERS = {
    "report":  handle_report_command,
    "ticket":  handle_ticket_command,
    "status":  handle_status_command,
}

@app.route("/slack/commands", methods=["POST"])
def slack_command():
    payload = request.get_json()
    key_command = payload["eventData"]["keyCommand"]
    args = payload["eventData"]["argumentCommand"]
    user_id = payload["eventData"]["userId"]
    response_url = payload["eventData"]["responseUrl"]

    handler = HANDLERS.get(key_command)
    if not handler:
        return jsonify({"commandResponse": {"text": f"Unknown command: `/{key_command}`"}})

    # Acknowledge immediately, process async
    handler(args, user_id, response_url)
    return jsonify({"commandResponse": {"text": "On it — give me a moment..."}})

Building Slack Integrations with Knit

Managing OAuth installs, token storage, token refresh, and multi-workspace support adds significant overhead before you've written a line of business logic. Knit handles the Slack integration infrastructure — auth, token lifecycle, and a normalised API layer — so you can focus on what your integration actually does.

Here's what Knit exposes for Slack:

Send Message

POST to chat.postMessage behind a single Knit endpoint. Pass a channel ID and a blocks array. The response returns ts and channel — both stored by Knit for downstream operations.

Use cases: Order notifications, incident alerts, digest messages, CRM event triggers, approval requests.

Update Message

Updates an existing message using its ts + channel pair. Pass as_user: true to update as the installing user rather than the bot.

Use cases: Live build status boards, approval resolution, updating order/ticket status without channel noise.

List Channels

Wraps conversations.list with cursor-based pagination handled automatically. Returns id, name, and is_private for each channel. Supports filtering by types.

Use cases: Channel pickers in your UI, compliance audits, onboarding automation (add new users to default channels).

List DM IDs

Retrieves the DM channel IDs for users the bot has existing conversations with. Useful for mapping your internal user records to Slack DM channels without repeatedly calling users.lookupByEmail.

Get DM ID from Email

Single call to resolve an email address to a Slack user ID — the equivalent of users.lookupByEmail. Use the returned id as the channel in a Send Message call to DM that user directly.

Use cases: HR onboarding flows, IT support ticket updates, sales/support follow-up DMs.

Register Bot Command (Slash Commands)

Register a slash command and a destination URL. When a user fires the command, Knit forwards the full event payload — including command, text, keyCommand, argumentCommand, userId, channelId, and responseUrl — to your endpoint, signed with an X-Knit-Signature header for verification.

Your endpoint returns a commandResponse object with blocks and/or text, and Knit delivers it back to Slack. For async operations, use the responseUrl from the forwarded payload.

Use cases: /report, /ticket, /status, /approve — any command that needs to query or trigger something in your backend.

‍

What to Build First

If you're starting a Slack integration from scratch, here's a sensible sequence:

1. Create your Slack app at api.slack.com/apps and set your required scopes.
2. Implement the OAuth install flow and store bot tokens per workspace.
3. Start with chat.postMessage — get a working notification flowing before adding complexity.
4. Add chat.update once you have messages being sent — live-updating messages is one of the highest-value Slack UX patterns.
5. Add slash commands if your users need to trigger actions from within Slack.
6. Add Events API subscriptions if you need to react to things happening in Slack.

If you're integrating Slack as one of several tools in a larger product and don't want to manage per-workspace OAuth and token storage for each one, Knit's Slack integration gives you all six of the above capabilities behind a single authenticated API — and adds every other integration you support through the same interface.

‍

The most common mistake in Slack integrations is starting with Incoming Webhooks because they're simple, then realising six months later that you need to post to different channels dynamically, update messages, or handle slash commands — and having to rebuild. Start with the Web API unless your use case genuinely only needs fixed-channel notifications.

Frequently Asked Questions

What is the difference between the Slack Web API and the Events API?

‍The Web API is request-driven: your server calls Slack to send messages, retrieve data, or update content. The Events API is event-driven: Slack calls your server when something happens in a workspace. Most integrations use both — the Web API to act, the Events API to react.

Which Slack API should I use to send a message?

‍Use chat.postMessage via the Slack Web API. Authenticate with a bot token (xoxb-), POST to https://slack.com/api/chat.postMessage with a channel ID and a blocks or text body. For direct messages, use the recipient's Slack user ID as the channel value.

How do I send a direct message to a Slack user from my application?

‍First look up the user's Slack ID by calling users.lookupByEmail with their email address. Then call chat.postMessage using that user ID as the channel parameter. The user will receive the message in their DMs from your app's bot.

What are Slack OAuth scopes and which ones do I need?

‍Scopes are permissions your app requests when a user installs it. For a basic messaging integration you need: chat:write (post messages), users:read.email (look up users by email), channels:read (list channels), and commands (if you're adding slash commands). Only request scopes you actually use.

What is Slack Socket Mode and when should I use it?

‍Socket Mode lets your app receive Slack events over a WebSocket connection instead of a public HTTP endpoint. Use it during local development when you don't have a public URL, or in production environments behind a firewall. For public-facing production apps, the Events API over HTTP is the standard approach.

Does the Slack Web API have rate limits?

‍Yes. Slack uses a tier system: chat.postMessage is Tier 3 (~50 requests per minute per channel), conversations.list is Tier 2 (~20 req/min), and users.lookupByEmail is Tier 4 (~100 req/min). Exceeding limits returns HTTP 429 with a Retry-After header. Always implement exponential backoff retry logic.

How do I handle Slack slash commands in my backend?

‍Register your slash command in your Slack app settings with an endpoint URL. Slack will POST a payload to that URL whenever the command is used. You must respond within 3 seconds — for longer operations, return an immediate acknowledgment and use the responseUrl from the payload to send the actual response asynchronously.

‍

How to Get a Slack Bot Token

To get a Slack bot token, create an app at api.slack.com/apps ("Create New App" → "From scratch"), open OAuth & Permissions, add the Bot Token Scopes your integration needs (such as chat:write), click Install to Workspace, approve the permissions, and copy the Bot User OAuth Token — it starts with xoxb-. Use that token in the Authorization: Bearer header to call Slack's Web API.

The rest of this page covers token types, where the credential goes, a working code sample, and the errors you'll hit if a scope is missing.

Prerequisites

A Slack workspace where you can install apps, or an admin who can approve the install.

A rough idea of which Bot Token Scopes your integration needs up front - adding scopes after install requires reinstalling the app, which generates a new token (Slack Developer Docs, App management quickstart).

If your integration needs to act as a specific person rather than a bot, you want a user token (xoxp-) instead - see the note near the bottom of this page.

Step-by-step: creating a Slack bot token

Where the credential goes

Slack's Web API accepts the token as a bearer token in the Authorization header (Slack Developer Docs, Tokens):

Authorization: Bearer xoxb-...

The word Bearer is case-sensitive. For some POST endpoints, you can alternatively send the token as a token= form field with Content-Type: application/x-www-form-urlencoded.

Connector-specific gotcha: a bot token's permissions are frozen at install time. If you add a new Bot Token Scope later, your existing xoxb- token does not gain that permission — you have to reinstall the app to the workspace (generating a new token) before the scope takes effect. A large share of missing_scope errors are really "I added the scope in the dashboard, but never reinstalled."

A few other things to know:

Lifetime: bot tokens (xoxb-) don't expire on their own and remain valid until revoked or the app is uninstalled. Apps that opt into Slack's token rotation get short-lived access tokens (around 12 hours) plus a refresh token instead (Slack Developer Docs, Tokens).

Revocation: call auth. revoke, or uninstall the app from the workspace's app management settings — either invalidates the token immediately.

Scopes: request the minimum Bot Token Scopes your integration needs, and add more only when required (then reinstall).

If you need a user token or a multi-workspace OAuth flow

For apps installed by many different workspaces, use the OAuth v2 install flow: send users to https://slack.com/oauth/v2/authorize?client_id=...&scope=<bot_scopes>&user_scope=<user_scopes>&redirect_uri=.... Slack redirects back with a temporary code (valid 10 minutes), which you exchange at oauth.v2.access for an access_token (bot, xoxb-) and, if you requested user_scope, an authed_user.access_token (user, xoxp-) (Slack Developer Docs, Installing with OAuth):

curl -F code=1234
-F client_id="$SLACK_CLIENT_ID"
-F client_secret="$SLACK_CLIENT_SECRET"
https://slack.com/api/oauth.v2.access

Minimal working example

This calls auth.test, which confirms the token is valid and returns basic identity info - a good smoke test for a new token.

curl:

curl -X POST https://slack.com/api/auth.test 

-H "Authorization: Bearer $SLACK_BOT_TOKEN"

Node.js:

const res = await fetch("https://slack.com/api/auth.test", {

method: "POST",

headers: {

Authorization: Bearer ${process.env.SLACK_BOT_TOKEN},

},

});
const data = await res.json();

console.log(data.team, data.user, data.bot_id);

Store SLACK_BOT_TOKEN as an environment variable — never hard-code it, and never commit it to source control.

Common errors and fixes

Why am I getting invalid_auth?

‍
The token is missing, malformed, or has been revoked (often via app uninstall). Check that the header reads Authorization: Bearer xoxb-... with no extra quotes, and confirm the app is still installed to the workspace under OAuth & Permissions (Slack Developer Docs, Tokens).

Why am I getting missing_scope?

‍
The response body includes needed and provided fields showing exactly which scope is required and which scopes your token actually has. Add the missing Bot Token Scope under OAuth & Permissions in your app's settings, then reinstall the app to the workspace — adding the scope alone doesn't update existing tokens (Slack Developer Docs, App management quickstart).

Why am I getting ratelimited?

‍
You've exceeded the per-method rate limit for your app in this workspace. Slack returns a 429 with a Retry-After header telling you how many seconds to wait before retrying (Slack Developer Docs, Rate limits).

The faster way

Creating and reinstalling a Slack app to fix scope issues is manageable for one workspace. It gets harder once your integration needs to support many workspaces, each with its own installed scopes, token lifecycles, and rate-limit tiers - on top of whatever other communication tools you're connecting. Knit's unified API handles Slack's OAuth installs and token storage, normalizes messaging and channel data across connectors, and manages rate-limit backoff for you. See the Slack API overview for what's available, or book a demo to see it against your own workspace. You can also sign up for free and connect a sandbox Slack workspace in a few minutes.

FAQ

Where do I find my Slack bot token after creating it?

‍
After you click "Install to Workspace" and approve the permissions, Slack shows the Bot User OAuth Token (starting with xoxb-) on the OAuth & Permissions page of your app. You can return to this page any time to copy it again - unlike some platforms, Slack doesn't hide it after the first view, but you should still store it as a secret.

What's the difference between a bot token (xoxb-) and a user token (xoxp-)?

‍
A bot token belongs to the app's bot user and is shared across the workspace install — it's the recommended default for most integrations. A user token acts on behalf of the specific person who authorized the app, with that person's own permissions. Use a bot token unless your integration specifically needs to act as a particular human user, such as posting messages that appear to come from them.

Do Slack bot tokens expire?

‍
No, not by default - xoxb- tokens remain valid until revoked via auth.revoke or until the app is uninstalled from the workspace. Apps that enable Slack's token rotation feature instead get short-lived access tokens (about 12 hours) and a refresh token, which Knit handles automatically for connected workspaces.

Why is my newly added scope not working?

‍
Adding a Bot Token Scope in your app's settings doesn't change tokens that were already issued. You need to reinstall the app to the workspace (or have the user reauthorize), which generates a new token that includes the added scope. This is the most common cause of missing_scope errors after a configuration change.

Is the Slack API free to use with a bot token?

‍
Yes - creating an app, installing it, and calling the Web API is free. Usage is governed by per-method rate limit tiers (roughly 1 to 100+ requests per minute, depending on the method), and some methods have additional limits for newer apps. Knit doesn't charge extra for Slack access either, and manages the rate-limit handling across connectors for you.

Sources:Tokens — Slack Developer Docs (https://docs.slack.dev/authentication/tokens)App management quickstart — Slack Developer Docs (https://docs.slack.dev/app-management/quickstart-app-settings)Installing with OAuth — Slack Developer Docs (https://docs.slack.dev/authentication/installing-with-oauth)Rate limits — Slack Developer Docs (https://docs.slack.dev/apis/web-api/rate-limits/)Slack setup — Knit Docs (https://developers.getknit.dev/docs/slack)

To get a GitHub personal access token, sign in to GitHub, go to Settings → Developer settings → Personal access tokens, choose Fine-grained tokens (or Tokens (classic)), click Generate new token, set an expiration and the permissions or scopes you need, then click Generate token. Copy the token immediately — GitHub shows it only once — and use it in the Authorization: Bearer header of your API requests.

That's the short version. The rest of this page covers which token type to pick, exactly which scopes to grant, a working code sample, and the errors you'll hit if a permission is missing.

Prerequisites

• A GitHub account with a verified email address (GitHub blocks token creation until your email is verified).
• Decide your resource owner up front: a fine-grained token is scoped to either your personal account or a single organization you belong to, not both.
• If the token needs to touch an organization's private repos, check whether that org restricts personal access tokens — an org admin may need to approve fine-grained tokens or allow classic PAT access before your token works.

Step-by-step: creating a fine-grained personal access token

GitHub recommends fine-grained tokens over classic tokens for new integrations, because you can scope them to specific repos and specific permissions instead of broad account-wide scopes (GitHub Docs, Managing your personal access tokens).

1. In the top-right corner of any GitHub page, click your profile photo, then Settings.
2. In the left sidebar, click Developer settings.
3. Under Personal access tokens, click Fine-grained tokens, then Generate new token.
4. Give it a Token name, and set an Expiration — up to 366 days, or no expiration if your org permits it. For anything long-running, pick the longest allowed expiration and put a renewal reminder on your calendar.
5. Under Resource owner, pick your account or the organization whose data you need.
6. Under Repository access, choose Only select repositories and pick the repos this token actually needs. "All repositories" works, but it defeats the point of a fine-grained token.
7. Under Permissions, grant only what the endpoints you're calling require — for example, Contents: Read-only to read files, or Issues: Read and write to create and comment on issues. Each REST endpoint's doc page lists the exact permission it needs.
8. Click Generate token and copy it somewhere safe. If your org requires approval for fine-grained tokens, the token stays in pending state — and read-only on public data — until an admin approves it.

Some endpoints (Packages, the Checks API, public repos you don't own) still don't support fine-grained tokens (limitations). For those, use Tokens (classic) instead: Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic), name it, set an expiration, check the scopes you need (repo covers most repository read/write cases), and generate. Knit's own GitHub setup guide uses this classic flow with repo, read:org, read:user, and user:email (Knit Docs — GitHub).

Where the credential goes

GitHub's REST API expects the token in a standard bearer header:

Authorization: Bearer YOUR-TOKEN

GitHub also still accepts the older Authorization: token YOUR-TOKEN form, but Bearer is what current docs and examples use (GitHub Docs, Authenticating to the REST API).

A few things to keep in mind:

• Lifetime: fine-grained tokens expire on the date you set (max 366 days, or no expiration if your org allows it). Classic tokens can be set to never expire, but GitHub auto-revokes any token — classic or fine-grained — that goes unused for a year.
• Refresh: personal access tokens don't refresh themselves. When one expires, you generate a new one and update wherever it's stored — there's no refresh-token flow like OAuth.
• Scopes/permissions: grant the minimum. A fine-grained token with contents: read can't accidentally delete a repo; a classic token with repo can do almost anything to every repo you can access. Store the token in an environment variable or secrets manager — never commit it.

Minimal working example

This calls GET /user, which returns the profile of the token's owner — a good smoke test for any new token.

curl:

curl -H "Authorization: Bearer $GITHUB_TOKEN" \
     -H "Accept: application/vnd.github+json" \
     -H "X-GitHub-Api-Version: 2026-03-10" \
     https://api.github.com/user

Node.js:

	const res = await fetch("https://api.github.com/user", {
  headers: {
    Authorization: `Bearer ${process.env.GITHUB_TOKEN}`,
    Accept: "application/vnd.github+json",
    "X-GitHub-Api-Version": "2026-03-10",
  },
});

const data = await res.json();
console.log(data.login);

Both send the X-GitHub-Api-Version header, which GitHub recommends pinning so a future API version change doesn't silently alter your response shape (GitHub Docs, Authenticating to the REST API).

Common errors and fixes

Why am I getting "Bad credentials" with a 401?

‍The token is missing, malformed, expired, or was revoked. Double-check the header reads Authorization: Bearer <token> with no extra quotes or whitespace, and confirm the token still exists under Settings → Developer settings — GitHub auto-deletes personal access tokens that sit unused for a year (GitHub Docs, Managing your personal access tokens).

Why do I get "Resource not accessible by personal access token"?

‍Your token doesn't have the scope or permission that endpoint needs. For fine-grained tokens, check the response's X-Accepted-GitHub-Permissions header — it lists exactly what's required — then add that permission to the token. For classic tokens, you likely need a broader scope like repo instead of public_repo (GitHub Docs, Troubleshooting the REST API).

Why am I hitting a 403/429 rate limit so quickly?

‍Unauthenticated requests are capped at 60/hour; authenticated requests get 5,000/hour. If x-ratelimit-remaining is 0, wait until the time in x-ratelimit-reset (UTC epoch seconds) before retrying — retrying immediately just burns more of your secondary rate limit (GitHub Docs, Rate limits for the REST API).

The faster way

Generating and rotating PATs is fine for a single script. It gets messier once you're supporting GitHub alongside Jira, Zendesk, or a dozen other ticketing tools — each with its own auth quirks, scopes, and expiry rules. Knit's unified ticketing API handles GitHub's OAuth and PAT flows, normalizes the endpoints across connectors, and refreshes credentials so you don't have to build that machinery yourself. See the GitHub API overview for what's available, or book a demo to see it against your own GitHub org. You can also sign up free and connect a sandbox GitHub account in a few minutes.

FAQ

Where do I find my GitHub personal access token after creating it?

‍GitHub shows the token value exactly once, right after you click "Generate token" — copy it then, because it's never displayed again. Lost it? Generate a new one. Existing tokens (without values) live under Settings → Developer settings → Personal access tokens, where you can check scopes, expiration, and delete unused ones.

What's the difference between a fine-grained and a classic personal access token?

‍Fine-grained tokens scope to specific repos and specific permissions; classic tokens use broad scopes like repo that apply everywhere you have access. Knit's GitHub setup currently uses classic scopes (repo, read:org, read:user, user:email) because a few endpoints — Packages, the Checks API, public repos you don't own — still aren't supported by fine-grained tokens.

Can I use a personal access token to access an organization's repositories?

‍Yes, if the org allows it and you already have access to those repos — a token can't grant access you don't have. Org admins can restrict or require approval for both token types, so a 403 against org repos usually means a policy setting, not a bad token.

How long does a GitHub personal access token last before I need a new one?

‍Fine-grained tokens expire on whatever date you set, up to 366 days out, or never if your org's policy allows it. Classic tokens can be set to never expire, but GitHub auto-deletes any token — classic or fine-grained — that sits unused for a year.

Is the GitHub API free to use with a personal access token?

‍Yes — token creation and REST API calls are free, subject to GitHub's rate limits (5,000 authenticated requests/hour for most accounts). If you're hitting that limit across multiple orgs, a GitHub App is worth a look — installation tokens get up to 15,000/hour on Enterprise Cloud.

Last verified and updated: 2026-06-13

Sources:

• Managing your personal access tokens — GitHub Docs
• Authenticating to the REST API — GitHub Docs
• Rate limits for the REST API — GitHub Docs
• Troubleshooting the REST API — GitHub Docs
• GitHub setup — Knit Docs

‍

The GitHub REST API gives you programmatic access to repositories, issues, pull requests, users, and webhooks — but before you write a single API call, you need to make the right authentication decision. Choose the wrong one and you'll either hit per-user rate limits at scale or spend weeks rebuilding your auth layer.

Quick answer: For production product integrations, use GitHub Apps — they authenticate at the installation level (not per-user), receive 15,000 API requests/hour per installation, and support fine-grained permissions. Use OAuth Apps when you need to act as the user. Use Personal Access Tokens for scripts and one-off automation only.

This guide covers everything you need to build a complete GitHub API integration: authentication setup for all three methods, REST API endpoints for issues, repos, users, and labels, webhook configuration with signature verification, rate limits, and three real-world integration patterns with working Python code.

If your product needs to support GitHub alongside other issue trackers like Jira, Linear, or Asana, there's a unified approach worth knowing about — covered in the Building with Knit section.

The GitHub API: REST, GraphQL, and Webhooks

GitHub exposes three API surfaces. Understanding which to use before you start building saves significant refactoring later.

REST API is the right choice for the vast majority of product integrations. The GraphQL API is useful when you need to fetch nested relationships (issues with their labels, assignees, and comments) in a single query and want to avoid over-fetching. Webhooks are event-driven and complement REST — they notify your server when something happens, then you call REST to get full details.

The GitHub REST API base URL is https://api.github.com. All endpoints accept and return JSON. The API version is specified via the X-GitHub-Api-Version header — always pin this to avoid breaking changes:

GET /repos/{owner}/{repo}/issues
Authorization: Bearer {token}
Accept: application/vnd.github+json
X-GitHub-Api-Version: 2022-11-28

‍

Authentication: GitHub Apps vs OAuth Apps vs Personal Access Tokens

This is the most consequential decision in any GitHub integration. Here's what each approach actually means for a production system:

Option 1: GitHub Apps (Recommended for Product Integrations)

GitHub Apps is the most powerful option and the right default for any B2B product integration. A GitHub App is installed on an organization or repository, not tied to a user account, and generates short-lived installation tokens.

Step 1: Register a GitHub App

Go to Settings → Developer settings → GitHub Apps → New GitHub App. Key fields:

• Webhook URL: your server's endpoint for incoming events
• Permissions: select only what you need (Issues: Read & Write, Metadata: Read)
• Where can this GitHub App be installed? → Any account (for multi-tenant products)

GitHub generates a private key (.pem file) and an App ID. Store both securely.

Step 2: Generate a JWT

import jwt
import time
from pathlib import Path

def generate_github_jwt(app_id: str, private_key_path: str) -> str:
    private_key = Path(private_key_path).read_text()
    payload = {
        "iat": int(time.time()) - 60,       # Issued at (60s buffer for clock skew)
        "exp": int(time.time()) + (10 * 60), # Expires in 10 minutes (max)
        "iss": app_id
    }
    return jwt.encode(payload, private_key, algorithm="RS256")

Step 3: Exchange the JWT for an Installation Token

import requests

def get_installation_token(jwt_token: str, installation_id: str) -> str:
    """
    Installation tokens expire after 1 hour.
    Cache and refresh them before expiry in production.
    """
    response = requests.post(
        f"https://api.github.com/app/installations/{installation_id}/access_tokens",
        headers={
            "Authorization": f"Bearer {jwt_token}",
            "Accept": "application/vnd.github+json",
            "X-GitHub-Api-Version": "2022-11-28"
        }
    )
    data = response.json()
    return data["token"]  # This is your installation access token

The installation token is used exactly like any other Bearer token for subsequent API calls. Because it expires in 1 hour, build a caching layer that refreshes tokens 5 minutes before expiry.

Step 4: Redirect users to install your GitHub App

https://github.com/apps/{app-name}/installations/new

After installation, GitHub redirects to your callback URL with an installation_id. Store this per-customer in your database.

If you're building a product that needs to support GitHub alongside other issue trackers — Jira, Linear, Asana — managing GitHub Apps installation tokens per customer, while also handling different auth flows for every other tool, quickly becomes a significant engineering overhead. Knit handles GitHub auth (OAuth and PAT) and normalises the API surface across all your supported ticketing tools, so you write the integration once. See getknit.dev/integration/github.

Option 2: OAuth Apps (User-Acting Flows)

Use OAuth Apps when your integration needs to act as the user — for example, creating issues on behalf of the authenticated user, or reading private repos the user has access to.

OAuth Flow:

# Step 1: Redirect user to GitHub
auth_url = (
    "https://github.com/login/oauth/authorize"
    f"?client_id={CLIENT_ID}"
    f"&redirect_uri={REDIRECT_URI}"
    f"&scope=repo,read:user"
    f"&state={generate_csrf_token()}"  # Always validate state to prevent CSRF
)

# Step 2: Exchange code for token (after redirect back)
def exchange_code_for_token(code: str) -> str:
    response = requests.post(
        "https://github.com/login/oauth/access_token",
        data={
            "client_id": CLIENT_ID,
            "client_secret": CLIENT_SECRET,
            "code": code
        },
        headers={"Accept": "application/json"}
    )
    return response.json()["access_token"]

OAuth App tokens do not expire automatically, but users can revoke them at any time. Build webhook listeners for the github_app_authorization event to detect revocations and clean up stored tokens accordingly.

Option 3: Personal Access Tokens

PATs are the simplest option — generate one in Settings → Developer settings → Personal access tokens — but they're fundamentally single-user. All API calls are attributed to the token owner, which creates audit and attribution problems in multi-tenant products. Use PATs for CI/CD pipelines, internal automation, and developer tooling only.

Fine-grained PATs (currently in beta) allow scoping to specific repositories and actions, making them a reasonable choice for tightly controlled automation scenarios.

For step-by-step instructions, see How to Get a GitHub Personal Access Token

Key GitHub REST API Endpoints

Issues

Issues are the core resource for most GitHub integrations. GitHub's Issues API also returns pull requests — always check for the pull_request field if you want to exclude PRs.

List issues in a repository:

def list_issues(owner: str, repo: str, token: str, state: str = "open") -> list:
    """
    Returns up to 100 issues per page.
    Iterate Link headers for full pagination.
    pull_request field is present on PRs — filter if needed.
    """
    issues = []
    url = f"https://api.github.com/repos/{owner}/{repo}/issues"
    params = {"state": state, "per_page": 100}
    headers = {
        "Authorization": f"Bearer {token}",
        "Accept": "application/vnd.github+json",
        "X-GitHub-Api-Version": "2022-11-28"
    }

    while url:
        response = requests.get(url, params=params, headers=headers)
        response.raise_for_status()
        issues.extend([i for i in response.json() if "pull_request" not in i])
        
        # GitHub returns pagination via Link header
        link_header = response.headers.get("Link", "")
        url = extract_next_url(link_header)  # Parse rel="next" from header
        params = {}  # Next URL already includes params

    return issues

Create an issue:

def create_issue(owner: str, repo: str, token: str,
                 title: str, body: str, labels: list = None,
                 assignees: list = None) -> dict:
    response = requests.post(
        f"https://api.github.com/repos/{owner}/{repo}/issues",
        headers={
            "Authorization": f"Bearer {token}",
            "Accept": "application/vnd.github+json",
            "X-GitHub-Api-Version": "2022-11-28"
        },
        json={
            "title": title,
            "body": body,
            "labels": labels or [],
            "assignees": assignees or []
        }
    )
    response.raise_for_status()
    return response.json()  # Returns full issue object including issue number and URL

Update an issue (assign, label, close):

def update_issue(owner: str, repo: str, issue_number: int, token: str, **fields) -> dict:
    """
    Supports: title, body, state (open/closed), labels, assignees, milestone.
    """
    response = requests.patch(
        f"https://api.github.com/repos/{owner}/{repo}/issues/{issue_number}",
        headers={
            "Authorization": f"Bearer {token}",
            "Accept": "application/vnd.github+json",
            "X-GitHub-Api-Version": "2022-11-28"
        },
        json=fields
    )
    response.raise_for_status()
    return response.json()

Repositories

# List repositories for an organization
GET /orgs/{org}/repos?type=all&per_page=100

# Get a specific repository
GET /repos/{owner}/{repo}

# List repository collaborators
GET /repos/{owner}/{repo}/collaborators

Users and Members

# Get the authenticated user
GET /user

# Get a user by username
GET /users/{username}

# List organization members
GET /orgs/{org}/members

Labels and Milestones

# List all labels in a repository
GET /repos/{owner}/{repo}/labels

# Create a label
POST /repos/{owner}/{repo}/labels
Body: {"name": "bug", "color": "d73a4a", "description": "Something isn't working"}

# List milestones
GET /repos/{owner}/{repo}/milestones?state=open

Webhooks: Real-Time Event Handling

Webhooks let GitHub push events to your server rather than requiring you to poll the API. Configure them in repository or organization settings, or programmatically via the API.

Create a webhook via the API:

def create_webhook(owner: str, repo: str, token: str,
                   payload_url: str, secret: str, events: list) -> dict:
    response = requests.post(
        f"https://api.github.com/repos/{owner}/{repo}/hooks",
        headers={
            "Authorization": f"Bearer {token}",
            "Accept": "application/vnd.github+json",
            "X-GitHub-Api-Version": "2022-11-28"
        },
        json={
            "name": "web",
            "active": True,
            "events": events,  # e.g. ["issues", "pull_request", "push"]
            "config": {
                "url": payload_url,
                "content_type": "json",
                "secret": secret,
                "insecure_ssl": "0"
            }
        }
    )
    response.raise_for_status()
    return response.json()

Verifying Webhook Signatures

Every GitHub webhook payload includes an X-Hub-Signature-256 header. You must verify this on every incoming request — skip this step and your endpoint can be spoofed by anyone who discovers its URL.

import hmac
import hashlib
from flask import Flask, request, abort

app = Flask(__name__)
WEBHOOK_SECRET = b"your-webhook-secret"

@app.route("/webhook/github", methods=["POST"])
def handle_github_webhook():
    # Verify signature before processing anything
    signature_header = request.headers.get("X-Hub-Signature-256", "")
    if not signature_header.startswith("sha256="):
        abort(400, "Missing or malformed signature")

    expected_sig = hmac.new(
        WEBHOOK_SECRET,
        request.data,           # Raw bytes — don't use parsed JSON here
        hashlib.sha256
    ).hexdigest()

    received_sig = signature_header[7:]  # Strip "sha256=" prefix

    # Constant-time comparison prevents timing attacks
    if not hmac.compare_digest(expected_sig, received_sig):
        abort(401, "Invalid signature")

    # Safe to process the payload now
    payload = request.json
    event_type = request.headers.get("X-GitHub-Event")

    if event_type == "issues":
        handle_issue_event(payload)
    elif event_type == "pull_request":
        handle_pr_event(payload)

    return "", 200

def handle_issue_event(payload: dict):
    action = payload["action"]  # opened, closed, labeled, assigned, etc.
    issue = payload["issue"]
    repo = payload["repository"]

    if action == "opened":
        print(f"New issue #{issue['number']} in {repo['full_name']}: {issue['title']}")

Supported webhook events for issue integrations: issues, issue_comment, label, milestone, pull_request, push, repository.

GitHub retries failed webhook deliveries with exponential backoff for up to 72 hours. Return a 200 response immediately on receipt and process the payload asynchronously to avoid delivery timeouts (GitHub expects a response within 10 seconds).

Rate limit status is returned in every response:

‍

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4823
X-RateLimit-Reset: 1747353600   # Unix timestamp when the limit resets
X-RateLimit-Used: 177

When X-RateLimit-Remaining reaches 0, GitHub returns 403 Forbidden with a Retry-After header. Build rate limit handling into your HTTP client from the start:

def github_request(url: str, token: str, **kwargs) -> requests.Response:
    response = requests.get(url, headers={
        "Authorization": f"Bearer {token}",
        "Accept": "application/vnd.github+json",
        "X-GitHub-Api-Version": "2022-11-28"
    }, **kwargs)

    if response.status_code == 403 and "X-RateLimit-Remaining" in response.headers:
        if response.headers["X-RateLimit-Remaining"] == "0":
            reset_time = int(response.headers["X-RateLimit-Reset"])
            wait = max(0, reset_time - int(time.time())) + 5  # 5s buffer
            time.sleep(wait)
            return github_request(url, token, **kwargs)  # Retry

    response.raise_for_status()
    return response

For secondary rate limits (triggered by too many concurrent requests), watch for Retry-After in the response headers and honor it exactly.

3 Common GitHub Integration Patterns

Pattern 1: Sync Issues from GitHub to Your Product

The most common integration pattern: pull issues from one or more GitHub repos and display or sync them inside your product.

import requests
import time

def sync_all_issues(installations: list, token_manager) -> list:
    """
    Full issue sync across multiple repositories.
    Returns a normalised list of issues for storage.
    """
    all_issues = []

    for installation in installations:
        token = token_manager.get_token(installation["id"])  # Cached + auto-refreshed

        for repo in installation["repos"]:
            owner, name = repo["owner"], repo["name"]
            page_url = f"https://api.github.com/repos/{owner}/{name}/issues"
            params = {"state": "all", "per_page": 100}

            while page_url:
                resp = requests.get(page_url, params=params, headers={
                    "Authorization": f"Bearer {token}",
                    "Accept": "application/vnd.github+json",
                    "X-GitHub-Api-Version": "2022-11-28"
                })
                resp.raise_for_status()

                for issue in resp.json():
                    if "pull_request" in issue:
                        continue  # Skip PRs

                    all_issues.append({
                        "id": issue["number"],
                        "title": issue["title"],
                        "state": issue["state"],
                        "assignees": [a["login"] for a in issue["assignees"]],
                        "labels": [l["name"] for l in issue["labels"]],
                        "url": issue["html_url"],
                        "created_at": issue["created_at"],
                        "updated_at": issue["updated_at"],
                        "repo": f"{owner}/{name}"
                    })

                # Parse next page from Link header
                link = resp.headers.get("Link", "")
                next_url = next(
                    (p.split(";")[0].strip("<>") for p in link.split(",")
                     if 'rel="next"' in p), None
                )
                page_url = next_url
                params = {}

    return all_issues

Pattern 2: Create Issues from Your Product

When a user creates a task in your product and wants it to appear in GitHub:

def create_github_issue_from_task(task: dict, repo_config: dict, token: str) -> dict:
    """
    Maps your product's task model to a GitHub issue.
    Returns the created issue with GitHub's issue number for cross-referencing.
    """
    # Map your assignees to GitHub usernames
    github_assignees = [
        repo_config["user_mapping"].get(uid)
        for uid in task.get("assignee_ids", [])
        if repo_config["user_mapping"].get(uid)
    ]

    # Map your labels/tags to GitHub label names
    github_labels = [
        repo_config["label_mapping"].get(tag)
        for tag in task.get("tags", [])
        if repo_config["label_mapping"].get(tag)
    ]

    response = requests.post(
        f"https://api.github.com/repos/{repo_config['owner']}/{repo_config['repo']}/issues",
        headers={
            "Authorization": f"Bearer {token}",
            "Accept": "application/vnd.github+json",
            "X-GitHub-Api-Version": "2022-11-28"
        },
        json={
            "title": task["title"],
            "body": f"{task['description']}\n\n---\n*Created via {task['source']}*",
            "assignees": github_assignees,
            "labels": github_labels,
            "milestone": repo_config.get("milestone_id")
        }
    )
    response.raise_for_status()
    github_issue = response.json()

    # Store the GitHub issue number in your database for future updates
    return {
        "github_issue_number": github_issue["number"],
        "github_issue_url": github_issue["html_url"],
        "github_issue_id": github_issue["id"]
    }

Pattern 3: Bidirectional Status Sync via Webhooks

Keep issue state in sync in real time — when a GitHub issue is closed, close the linked item in your product; and vice versa.

# Webhook handler (GitHub → your product)
def handle_issue_state_change(payload: dict):
    action = payload["action"]

    if action not in ("closed", "reopened"):
        return  # Only care about state changes

    github_issue_id = payload["issue"]["id"]
    new_state = "closed" if action == "closed" else "open"

    # Look up the linked task in your DB
    task_id = db.get_task_by_github_id(github_issue_id)
    if task_id:
        db.update_task_state(task_id, new_state)
        print(f"Synced GitHub issue {github_issue_id} → Task {task_id}: {new_state}")


# REST handler (your product → GitHub)
def close_github_issue_for_task(task_id: str, token: str):
    github_info = db.get_github_info_for_task(task_id)
    if not github_info:
        return

    update_issue(
        owner=github_info["owner"],
        repo=github_info["repo"],
        issue_number=github_info["issue_number"],
        token=token,
        state="closed"
    )

Building GitHub Integrations with Knit

GitHub Apps auth — JWTs, per-installation tokens that expire hourly, managing token refresh across multiple customer installations — is the part of a GitHub integration that adds the most engineering overhead for the least user-visible value.

Knit provides a unified ticketing API that handles GitHub authentication (OAuth and Personal Access Token flows) for your customers. Instead of building and maintaining the OAuth consent flow, token storage, and refresh logic, your customers connect their GitHub account once through Knit's auth layer. You call Knit's normalised endpoints using a single set of headers:

Authorization: Bearer {your-knit-api-token}
X-Knit-Integration-Id: {customer-integration-id}

This is particularly valuable if your product supports GitHub alongside other issue trackers — Jira, Linear, Asana, Zendesk, and more are all available through the same Knit interface, so you build the integration pattern once and it works across all of them.

The Knit APIs available for GitHub:

Example: fetch all teams in a GitHub org via Knit

‍

import requests

def get_github_teams_via_knit(knit_token: str, integration_id: str,
                               account_id: str) -> list:
    """
    Returns GitHub teams for the given org (account_id).
    No JWT generation, no installation tokens, no token refresh logic.
    """
    response = requests.get(
        "https://api.getknit.dev/v1.0/ticketing/groups",
        headers={
            "Authorization": f"Bearer {knit_token}",
            "X-Knit-Integration-Id": integration_id
        },
        params={"accountId": account_id}
    )
    response.raise_for_status()
    data = response.json()

    # Cursor-based pagination built in
    groups = data["data"]["groups"]
    next_cursor = data["data"]["pagination"].get("next")

    while next_cursor:
        response = requests.get(
            "https://api.getknit.dev/v1.0/ticketing/groups",
            headers={
                "Authorization": f"Bearer {knit_token}",
                "X-Knit-Integration-Id": integration_id
            },
            params={"accountId": account_id, "cursor": next_cursor}
        )
        page = response.json()
        groups.extend(page["data"]["groups"])
        next_cursor = page["data"]["pagination"].get("next")

    return groups

→ See the full GitHub integration on Knit: getknit.dev/integration/github

‍→ Knit's ticketing API docs: developers.getknit.dev

‍

What to Build First

If you're building a GitHub integration from scratch, this is the order that minimises rework:

1. Register your GitHub App and generate your private key — do this before writing any API code. Your App ID and private key are required for every subsequent step.
2. Build your installation token manager — a simple class that generates JWTs, exchanges them for installation tokens, and caches tokens until 5 minutes before expiry. Every other part of your integration depends on this.
3. Implement the OAuth installation flow — redirect users to install your app, capture the installation_id on callback, and store it per customer.
4. Set up your webhook endpoint with signature verification — register it while creating the GitHub App. Getting verification right from day one prevents security issues later.
5. Implement the issues endpoints — list, create, and update. These cover 80% of typical GitHub product integrations.
6. Build your user mapping layer — fetch org members and map them to your product's user identifiers. GitHub users don't expose email addresses via most endpoints, so login (username) is your reliable identifier.
7. Add label and milestone sync — fetch these once on installation and cache them; they change infrequently.
8. Wire up bidirectional status sync — close/reopen issues in response to both webhook events (GitHub → your product) and user actions (your product → GitHub).

Summary

‍

Frequently Asked Questions

What is the difference between GitHub Apps, OAuth Apps, and Personal Access Tokens?

GitHub Apps are the recommended approach for building integrations — they authenticate as the app itself, support fine-grained permissions, and receive 15,000 API requests/hour per installation. OAuth Apps authenticate as a user and are limited to the user's rate limit of 5,000 requests/hour. Personal Access Tokens are best for scripts and automation where a single user account controls access, but they do not scale across multiple users.

How do I authenticate with the GitHub REST API?

Pass your token in the Authorization header: Authorization: Bearer {token}. For GitHub Apps, generate a JWT signed with your app's private key, then exchange it for an installation access token via POST /app/installations/{installation_id}/access_tokens. For OAuth Apps and PATs, pass the token directly. Unauthenticated requests are limited to 60 requests per hour; authenticated requests get 5,000 per hour.

What are the GitHub REST API rate limits?

Unauthenticated requests: 60 per hour. Authenticated OAuth Apps and PATs: 5,000 requests per hour. GitHub Apps using installation tokens: 15,000 requests per hour per installation. Search API requests: 30 per minute for authenticated users, 10 per minute for unauthenticated. Rate limit status is returned on every response via X-RateLimit-Remaining and X-RateLimit-Reset headers.

How do GitHub webhooks work?

GitHub webhooks send HTTP POST payloads to a URL you configure whenever a subscribed event occurs. Every payload includes an X-Hub-Signature-256 header — an HMAC-SHA256 signature of the raw request body using your webhook secret. You must verify this signature on every incoming request. GitHub delivers at most one webhook per event and retries for up to 72 hours on delivery failure.

How do I list all issues from a GitHub repository via the API?

Use GET /repos/{owner}/{repo}/issues. By default this returns open issues and pull requests. Filter with state=open, state=closed, or state=all. Use labels, assignee, and milestone query params to narrow results. Results are paginated at 30 items per page by default — use per_page (max 100) and the Link response header to navigate pages. Pull requests are included in the issues endpoint; filter them out by checking for the pull_request field.

What is the difference between the GitHub REST API and GraphQL API?

The GitHub REST API has separate endpoints per resource and is the standard choice for most integrations. The GitHub GraphQL API (v4) lets you request exactly the fields you need in a single query, reducing over-fetching. Use REST when building straightforward CRUD integrations. Use GraphQL when you need to fetch deeply nested relationships — issues with their comments, labels, and assignees — in a single request.

How do I verify a GitHub webhook signature?

Compute HMAC-SHA256 of the raw request body using your webhook secret as the key. Compare this digest to the value in the X-Hub-Signature-256 header (prefixed with sha256=). Use a constant-time comparison function (like hmac.compare_digest in Python) to prevent timing attacks. Never process webhook payloads before verifying the signature.

Is there a simpler way to integrate GitHub without managing OAuth or GitHub Apps authentication myself?

Yes. Knit provides a unified ticketing API that handles GitHub authentication (OAuth and PAT) for you. Instead of implementing the OAuth flow, managing token storage, or dealing with per-user credentials, your customers connect their GitHub account once through Knit's auth layer. You then call Knit's normalised endpoints — for organisations, users, teams, and labels — without writing auth infrastructure. This is especially useful if you also need to support Jira, Linear, or Asana alongside GitHub, as Knit's same API surface covers all of them. → getknit.dev/integration/github

‍

‍

Last updated: June 2026

Note: This is a part of our API Security series where we solve common developer queries in detail with how-to guides, common examples, code snippets and a ready to use security checklist. Feel free to check other articles on topics such as authentication methods, rate limiting, API monitoring and more.

Below are some common API security FAQs that serve as a valuable resource for understanding, implementing, and maintaining the robust security measures necessary to protect your APIs and the valuable data they handle.

1. How to handle when a token expires – generate and store new?

When an authentication token used with your API expires, the best practice is to generate a new token and update it in your application's authentication system.

This process often involves sending a request to the authentication server, such as an OAuth 2.0 token endpoint, with necessary credentials to obtain a fresh token.

The new token should then be securely stored and used for subsequent API requests. Make sure to handle token expiration gracefully in your application code by checking the token's expiration time and obtaining a new one before it expires to avoid disruptions in API access.

If you're integrating with several third-party APIs, this refresh logic has to be built and maintained separately for each provider's OAuth implementation. Knit handles OAuth 2.0 authentication and token refresh automatically across its supported integrations, so your application doesn't need to implement or monitor this logic per platform.

2. How often should I perform security audits and testing for my APIs?

Regular security audits and testing are crucial for maintaining API security. The right cadence depends on your organization's risk tolerance, regulatory requirements, and how quickly your API ecosystem changes — but in practice, it works best as two layers: continuous, automated checks that run with every API change or release, and periodic formal audits that go deeper into architecture, access controls, and threat modeling.

As a general guideline:

• Perform security audits during the initial API design phase, before new endpoints go live.
• Run automated security checks — such as dependency and vulnerability scans — as part of your development and integration pipeline, on every significant change.
• Schedule formal security assessments, including penetration tests, at least annually — or semi-annually for higher-risk or customer-facing APIs.
• Conduct additional audits in response to emerging threats, major provider API changes, or high-profile security incidents in your industry.

3. What should I do in case of a security breach involving my API?

Most established incident-response frameworks — including those published by AWS and IBM — describe a similar lifecycle: prepare, detect and analyze, contain, eradicate and recover, and apply lessons learned. In the unfortunate event of a security breach involving your API, that lifecycle translates into the following steps:

• Contain the breach: Isolate affected systems or resources to prevent further damage.
• Notify relevant parties: Inform your internal security team, management, and legal counsel.
• Assess the scope: Determine the extent of the breach, what data may have been compromised, and how the breach occurred.
• Mitigate the issue: Address the security vulnerability or weakness that led to the breach. Patch any vulnerabilities and secure access points.
• Notify affected parties: Depending on data protection laws and regulations, you may need to notify affected customers or users about the breach.
• Enhance security: Review and strengthen your API security measures to prevent future breaches. Update security policies and train your team on security best practices.
• Cooperate with authorities: If required by law, cooperate with law enforcement agencies or data protection authorities during investigations.
• Communicate ethically: Maintain clear and transparent communication with stakeholders, including affected parties, throughout the incident response process.

Remember, having a well-documented incident response plan in place beforehand can greatly streamline your actions in case of a security breach involving your API.

4. How can I monitor and log API activity for security purposes?

Monitoring and logging API activity is essential for security. To achieve this, consider implementing the following:

• Utilize logging libraries: Use logging libraries or frameworks in your application code to record API interactions, including request details, response data, timestamps, and client information.
• Leverage API gateways: API gateways often provide built-in logging and monitoring features. They can capture data like request/response payloads, error codes, and client IPs.
• Utilize third-party tools: Explore security information and event management (SIEM) solutions, log analysis tools, or dedicated API monitoring services to centralize and analyze API logs.
• Set up alerts: Configure alerts and notifications based on predefined security thresholds, such as unusual request patterns, high error rates, or suspicious activities, to take immediate action when necessary.
• Structure and retain your logs: Use structured (JSON) logging so logs can be filtered and queried programmatically, mask or exclude sensitive fields such as tokens and personal data before they're written, and define a retention window — a common guideline is at least 30 days of readily-searchable storage plus longer-term archival for audits and incident investigations.

For example – Knit has a dedicated Logs and Issues page where the status of each API call and webhook for all your integrated accounts is available for a quick review on a single page. Knit continuously monitors all integrations and sends you automated alerts whenever a security threshold is reached.

[image: existing screenshot of Knit's Logs and Issues page — unchanged]

5. What is the best practice for API token expiration?

There's no single lifetime that applies to every API, but Google's Apigee team publishes a widely-cited starting point: configure access tokens to expire after around 30 minutes and refresh tokens after around 24 hours, then adjust both based on your application's security and usability needs. In practice, lifetimes vary a lot by provider — some issue access tokens valid for hours, others for days, and refresh tokens can range from a day to several months — so always check the specific API's documentation rather than assuming a default. Shorter access-token lifetimes limit how long a leaked token stays useful, while longer refresh-token lifetimes reduce how often users have to re-authenticate. If you're managing this across several integrations, Knit issues and refreshes OAuth tokens automatically for its supported platforms, so each provider's specific token lifetime is handled for you rather than tracked manually.

6. Is an expired API token a 401 or 403 error?

An expired API token should return a 401 Unauthorized response, not 403 Forbidden. The distinction matters for how your application handles the error: 401 means the credentials provided — including an expired or invalid token — aren't sufficient to authenticate the request at all, while 403 means the credentials are valid but the authenticated user or application doesn't have permission for that specific action. On a 401, the correct response is typically to refresh the token and retry the request; a 403 usually signals a permissions or scope issue that refreshing a token won't fix. Not every API follows this convention strictly, so it's worth checking a given provider's documentation, but 401 is the technically correct code for an expired token.

7. What should be part of an API security checklist?

A practical API security checklist covers both how requests are authenticated and how the API behaves once a request is inside the system. At minimum, it should include: using OAuth 2.0 or another modern authentication standard with appropriately short-lived tokens, enforcing rate limiting and throttling to prevent abuse, validating and sanitizing all input, encrypting data in transit and at rest, logging and monitoring API activity with alerts for anomalies, and maintaining a documented incident response plan. For a more detailed, ready-to-use checklist with examples, see our API Security 101 guide.

8. How does Knit help secure API integrations across multiple platforms?

Knit reduces API security risk by acting as a single, consistently-secured layer between your application and the HRIS, ATS, CRM, and other platforms it supports. Instead of your team building and maintaining separate authentication, token-refresh, and data-handling logic for each connected platform — each with its own security model — Knit handles OAuth flows, token refresh, and credential storage centrally, and normalizes data from every integration into a consistent format. Knit also provides a dedicated Logs and Issues dashboard so you can review the status of every API call and webhook across your integrated accounts from one place, with automated alerts when a security threshold is reached. For teams integrating with many third-party APIs, this consolidates what would otherwise be dozens of separate security surfaces into one that Knit maintains and monitors.

‍

Note: This is a part of our API Security 101 series where we solve common developer queries in detail with how-to guides, common examples and code snippets. Feel free to visit the smaller guides linked later in this article on topics such as authentication methods, rate limiting, API monitoring and more.

APIs are the connective tissueof modern software - every integration, mobile app, and automated workflowdepends on them. But every API endpoint is also a potential entry point forattackers, which makes understanding API security risks essential for any teamthat builds or relies on APIs.

The most common API securityrisks and threats include unauthorized access from weak or brokenauthentication, injection attacks, excessive data exposure, lack of ratelimiting, vulnerabilities introduced by third-party dependencies, human errorsuch as leaked credentials, and shadow APIs - undocumented endpoints thatbypass security review entirely. Many of these map directly to the OWASP API Security Top 10, the industry-standard framework for API vulnerabilities, whichthis guide's companion post on API Security 101 best practices covers in full.

In this post, we break down eachof these risks - what it looks like in practice, how it's typically exploited,and how to mitigate it - so you can assess where your own APIs (and thethird-party APIs you depend on) might be exposed.

TABLE OF CONTENTS

1. Unauthorized access

2. Broken authentication tokens

3. Injection attacks

4. Data exposure

5. Rate limiting and Denial of Service (DoS) attacks

6. Third-party dependencies

7. Human error

8. Shadow and undocumented APIs

9.  Consequences of API security breaches

10. FAQs

‍

Common risks to API security developers must know of

1. Unauthorized access 

‍

Unauthorized access happens whensomeone — a malicious actor, a former employee, or even another customer'sapplication — gains access to API endpoints or data they shouldn't be able toreach. This is typically the result of weak or missing authentication, overlypermissive access controls, or endpoints that don't verify a user's identityand permissions on every request.

For example, an endpoint like/api/users/12345/invoices might only check that a request includes a validtoken — not that the token actually belongs to user 12345. An attacker whosimply changes the ID in the URL could retrieve another customer's invoices.This is a textbook case of Broken Object Level Authorization, the #1 risk inthe OWASP API Security Top 10.

Mitigation: every request needsto be authenticated and authorized — not just at login, but on every call, witha check that the authenticated user actually has permission to access thespecific object being requested. Knit's API Security 101 guide coversauthentication and authorization methods in depth, including how to enforcethese per-object access checks.

‍

2. Broken authentication tokens

Broken authentication tokensoccur when the tokens used to verify a user's identity — session tokens, APIkeys, or JWTs — are predictable, long-lived, improperly stored, or not properlyi nvalidated. If an attacker obtains a valid token, they can impersonate thatuser for as long as the token remains valid.

A common real-world example issession hijacking: if a token doesn't expire, isn't tied to a specific deviceor IP address, or is exposed in a URL or log file, an attacker who captures itcan use it to access the account indefinitely — often without triggering anyalerts, since the requests look like normal traffic from an authenticated user.

Mitigation: issue short-livedaccess tokens with refresh tokens rather than long-lived credentials, storetokens securely, and invalidate tokens on logout or password change. Knit'sauthentication best practices section covers token lifecycle management forboth the APIs you build and the third-party APIs you integrate with.

‍

3. Injection attacks 

Injection attacks happen whenuntrusted input — from a URL parameter, form field, or API request body — is passed directly into a database query, command, or interpreter without beingvalidated or sanitized. The most common form is SQL injection, where anattacker manipulates input to run unintended database commands.

For example, if an API endpointbuilds a query like SELECT * FROM users WHERE id = '<input>' withoutsanitizing the input, an attacker could pass a value like ' OR '1'='1 toretrieve every row in the table instead of just one user's record.

Mitigation: always useparameterized queries or prepared statements instead of string concatenation,validate and sanitize every input against an expected format, and apply theprinciple of least privilege to database accounts used by APIs. Knit's sectionon input validation and parameter sanitization covers this pattern in moredepth.

‍

4. Data Exposure 

Data exposure — sometimes calledexcessive data exposure — happens when an API returns more information than theclient actually needs, relying on the front end to filter out sensitive fieldsrather than restricting them at the API level. Because API responses can beinspected directly, in browser dev tools, intercepted traffic, or by callingthe endpoint outside the intended app, any sensitive field included in aresponse is effectively exposed.

A common example: an endpointmeant to show a user's name and avatar in a directory actually returns the fulluser object, including email address, phone number, internal role, or otherfields the front end simply chooses not to display.

Mitigation: define explicitresponse schemas that include only the fields a given endpoint needs, neverrely on the client to filter sensitive data, and encrypt sensitive fields atrest and in transit. Knit's section on secure data transmission, encryption,and HTTPS covers the encryption side of this in detail.

‍

5. Rate Limiting and Denial of Service (DoS) Attacks

Without rate limiting, an APIhas no way to distinguish between normal usage and abuse — whether that's aclient accidentally retrying a failed request in a tight loop, a scraperpulling data far faster than intended, or a deliberate Denial of Service (DoS)attack designed to overwhelm the API with traffic until it becomes slow orunavailable for everyone.

The impact isn't limited todowntime: APIs without limits are also more vulnerable to brute-force attacksagainst login or token endpoints, since an attacker can attempt unlimitedpassword or token guesses without being throttled.

Mitigation: set per-client ratelimits based on an API key, token, or IP address, return an HTTP 429 (Too ManyRequests) response with a Retry-After header when limits are exceeded, andcombine hard limits with throttling so the API degrades gracefully under loadrather than failing outright. Knit's guide to API rate limiting and throttlingcovers these patterns — including how to handle 429 responses from third-partyAPIs — in more detail.

‍

6. Third-party dependencies

Most modern applications don'toperate in isolation — they call out to third-party APIs for payments,authentication, data enrichment, communications, and more. Each of thosedependencies extends your application's attack surface: a vulnerability, outage,or data breach at a third-party provider can compromise your application evenif your own code has no flaws at all.

This risk is easy tounderestimate because it's invisible until something goes wrong — a third-partyAPI that suddenly changes its authentication requirements, gets compromised, orquietly starts storing more of your users' data than you realized can allbecome your problem with little warning.

Mitigation: vet third-party APIsbefore integrating with them — review their security certifications, datahandling policies, and incident history — grant them the minimum access anddata they need, and prefer providers that are explicit about not retaining acopy of your data. Knit's section on third-party API security considerationscovers what to look for when evaluating an integration partner.

‍

7. Human error

Many of the most damaging APIsecurity incidents don't involve a sophisticated exploit at all — they comedown to a misconfiguration or a mistake. Common examples include API keys orcredentials accidentally committed to a public code repository, overly permissivedatabase or IAM permissions left in place after testing, debug or stagingendpoints left accessible in production, and documentation or API collectionsshared externally that contain live credentials.

Because these mistakes are ofteninvisible until they're exploited — a leaked key can sit in a public repositoryfor months before anyone notices — they're frequently the root cause behindincidents that initially look like sophisticated attacks.

Mitigation: use secret-scanningtools on your repositories, rotate any credentials that may have been exposed,apply least-privilege access by default, and review permissions and exposedendpoints on a regular cadence rather than only at launch. The API securitychecklist in Knit's API Security 101 guide is designed to catch exactly thesekinds of configuration gaps.

‍

8. Shadow and undocumented APIs

Shadow APIs are endpoints thatexist and are reachable in production but aren't tracked in your API inventory,documentation, or security review process. They're typically created duringrapid development — a developer spins up an endpoint for testing, an old APIversion is left running after a new one ships, or a feature is deprecated butits underlying endpoint is never decommissioned.

Because shadow APIs fall outsidenormal monitoring and review, they often lack the authentication, ratelimiting, and logging applied to documented endpoints — making them an attractive target. Attackers actively scan for these endpoints, since they're frequentlyless protected than an organization's primary, well-documented APIs.

Mitigation: maintain a complete, current inventory of every API endpointin production — including internal and deprecated ones — and decommissionunused endpoints rather than leaving them reachable. Knit's section on APIlifecycle management and decommissioning covers how to build this inventory andretirement process into your API lifecycle

‍

9. Consequences of API security breaches

The consequences of an APIsecurity breach extend well beyond the immediate incident. Depending on whatdata and systems are exposed, organizations can face direct financial losses,regulatory fines under frameworks like GDPR, costly incident response andremediation work, and reputational damage that affects customer trust longafter the breach itself is resolved.

For B2B platforms, a breach in one customer's data can also expose every other customer connected through thesame API — which is why addressing these risks isn't optional once an API ishandling real user data. The API security checklist in Knit's API Security 101guide is a practical starting point for working through these riskssystematically.

‍

‍

Take your API security to the next level

If you are dealing with a large number of API integration and looking for smarter solutions, check out unified API solutions like Knit. Knit ensures that you have access to high quality data faster in the safest way possible.

There are 3 ways Knit ensures maximum security.

• Knit is the only unified API in the market that does NOT store a copy of your end user data in its severs or share it with any third party. All of our syncs are event-based and happens via webhooks to ensure that your data is not subjected to any external threats during the transfer. Learn more about Knit's secure data sync here
• Knit complies with industry best practices and security standards. We are SOC2, GDPR and ISO27001 certified and always in the process of adding more security badges to our collection.
• We monitor Knit's infrastructure continuously with the finest intrusion detection systems. Plus, our super responsive support team is available 24*7 across all time zones to make sure if at all a security issue occurs, it is resolved immediately.

If you want to learn more about Knit Security Practices, please talk to one of our experts. We would love to talk to you

‍

FAQs

What are the common API security risks?

The most common API securityrisks include unauthorized access from weak or broken authentication, injectionattacks such as SQL injection, excessive data exposure through endpoints thatreturn more data than needed, lack of rate limiting that leaves APIs open todenial-of-service attacks, vulnerabilities introduced through third-partydependencies, human error such as leaked API keys or misconfigured permissions,and shadow APIs — undocumented endpoints that bypass security review. Thisguide covers each of these in depth, including concrete examples of how they'reexploited and how to mitigate them. For teams managing many third-partyintegrations, several of these risks — particularly third-party dependency andauthentication risk — are reduced by default through Knit's unified API, whichhandles authentication and doesn't retain a copy of integrated platforms' data.

What is the difference between an API vulnerability and an API attack?

An API vulnerability is aweakness in an API's design, code, or configuration — such as a missingauthorization check, an unvalidated input field, or an API key exposed in apublic repository — that could potentially be exploited. An API attack is theact of exploiting that vulnerability, such as an attacker manipulating arequest to access another user's data, injecting malicious input into a query,or flooding an endpoint with traffic to cause a denial of service. In practice,most vulnerabilities exist for some time before they're attacked, which is whyproactive steps like input validation, rate limiting, and regular securityaudits matter — they close the gap between a vulnerability existing and itbeing exploited, often before an attacker ever finds it.

What are shadow APIs and why are they a security risk?

Shadow APIs are API endpointsthat are live and reachable in production but aren't tracked in anorganization's API inventory, documentation, or security review process — oftenleft over from testing, old API versions, or deprecated features that were neverdecommissioned. They're a significant security risk because they typically lackthe authentication, rate limiting, and monitoring applied to documentedendpoints, making them an easier target for attackers who actively scan forexactly this kind of unmonitored access point. Shadow APIs are also harder topatch quickly, since a vulnerability can't be fixed in an endpoint the securityteam doesn't know exists. Maintaining a complete, current inventory of everyAPI endpoint — and decommissioning unused ones — is the most effective way toclose this gap, an approach covered in Knit's API lifecycle managementguidance.

How does broken authentication lead to API security breaches?

Broken authentication occurswhen the tokens, API keys, or session credentials used to verify a user'sidentity are predictable, long-lived, improperly stored, or not properlyinvalidated after logout or a password change. Knit removes a common source ofthis risk for the 100+ platforms it connects by handling OAuth flows, tokenrefresh, and credential storage automatically, so integrating teams don't haveto manage long-lived third-party credentials themselves. If an attacker obtainsa valid token through any of these weaknesses in your own API, they canimpersonate that user and access their data for as long as the token remainsvalid — often without triggering alerts, since the request looks like normaltraffic. Best practices include issuing short-lived access tokens with refreshtokens, storing tokens securely, and invalidating them on logout or passwordchange.

What is excessive data exposure in an API?

Excessive data exposure happenswhen an API response includes more information than the requesting clientactually needs — relying on the front end to filter out sensitive fields ratherthan restricting them at the API level itself. Because API responses can beinspected directly through browser developer tools, intercepted traffic, or bycalling the endpoint outside the intended application, any sensitive fieldincluded in a response — such as an email address, internal ID, or role — iseffectively exposed regardless of whether the interface displays it. Knitaddresses this for the data it processes by encrypting sensitive fields,including PII and credentials, with an additional layer of application-levelencryption beyond standard transport security. The fix at the API level is todefine explicit response schemas that return only the fields each endpointgenuinely needs.

How can third-party API dependencies introduce security risks?

Every third-party API yourapplication integrates with — for payments, authentication, data enrichment, orcommunications — extends your attack surface, because a vulnerability, outage,or data breach at that provider can compromise your application even if yourown code is secure. Knit addresses this directly: as a pass-through integrationlayer, Knit does not store a copy of your end users' data on its servers orshare it with any third party, syncing data via event-based webhooks instead ofretaining it in a database. This removes an entire category of third-party risk— a vendor's data retention practices can't expose your users' data if thatvendor never holds a copy of it. When evaluating any third-party API, reviewits security certifications, data retention policy, and incident history, andgrant it the minimum access it needs.

How does Knit reduce third-party API security risk for the integrations itconnects?

Knit reduces third-party APIsecurity risk in two ways: first, it handles authentication, token refresh, andcredential storage for every one of the 100+ HRIS, ATS, CRM, and otherplatforms it connects, removing a common source of broken-authentication riskfrom your integration layer. Second, Knit is built as a pass-through proxy — itdoes not store a copy of your end users' data on its servers or share it withany third party, and all syncs happen via event-based webhooks rather thanretained databases. Knit is also SOC2, GDPR, and ISO27001 certified, withcontinuously monitored infrastructure, intrusion detection, and 24/7 support,documented in full at getknit.dev/security. For teams managing dozens ofintegrations, this consolidates third-party API risk review into a single,audited layer instead of one per integration.

Does Knit follow the OWASP API Security Top 10 framework?

Knit's own API securitypractices align with the OWASP API Security Top 10 — the industry-standardframework covering risks like broken object-level authorization, brokenauthentication, and excessive data exposure, the same risks covered in thisguide. Knit's API Security 101 guide includes a full mapping of its securitybest practices to each of the ten OWASP categories, showing how each risk isaddressed in Knit's architecture and in the practices recommended for the APIsKnit connects to. While OWASP's list is aimed at anyone building or securingAPIs, it's a useful checklist for evaluating any third-party API — includingKnit — as part of a vendor security review.

‍

Note: This is our master guide on API Security where we solve common developer queries in detail with how-to guides, common examples and code snippets. Feel free to visit the smaller guides linked later in this article on topics such as authentication methods, rate limiting, API monitoring and more.

‍

Today, an average SaaS company relies on 350 integrations to share data and functionality, both internally andwith the tools their customers already use. That reliance makes API security afoundational requirement, not an afterthought — a single overlookedvulnerability can expose sensitive data, compromise user privacy, and disruptoperations for every customer connected through that API.

This guide is Knit's masterreference on API security. In it, you'll find:

•        The most common API security risks and how they happen

•        Eight best practices for securing your APIs, withpractical, step-by-step guidance

•        How these practices map to the OWASP API Security Top 10, the industry-standard framework for API vulnerabilities

•        An on-page API security checklist you can work throughdirectly (plus a downloadable version)

•        Answers to the API security questions developers askmost

Whether you're securing the APIsyou build or evaluating the third-party APIs you integrate with, thesepractices apply either way. Let's get started.

‍

TABLE OF CONTENTS

• API Security Risks

• API security best practices

1. API Authentication and Authorization methods

2. Secure data transmission: Encryption and HTTPS

3. Input validation and parameter sanitization

4. Rate limiting and Throttling

5. API monitoring and logging

6. Regular security audits and Penetration Testing

7. API lifecycle management and decommissioning

8. Third-Party API Security Considerations

• OWASP API Security Top 10: How These Practices Map

•      API security checklist

•        Common API security FAQs by developers

•        Enable maximum security for your API integrations withKnit

‍

‍

‍

API Security Risks

Before diving deeper into the API security best practices, it's crucial to have a solid grasp of the risks and threats that APIs can face. These risks can stem from various sources, both external and internal, and being aware of them is the first step towards effective protection. 

Here are some of the key API security risks to consider:

1. Unauthorized access
2. Broken authentication tokens
3. Injection attacks
4. Data exposure
5. Rate limiting and Denial of Service (DoS) attacks 
6. Third party dependencies
7. Human error

Read: Common Risks to API Security and their consequences where we discussed all these threats in detail

The old adage "prevention is better than cure" couldn't be more apt in the realm of API security, where a proactive approach is the key to averting devastating consequences for all parties involved.

Keeping this in mind, let’s dive deeper into our API security best practices.

‍

API security best practices

Ensuring API security means providing a safe way for authentication, authorization, data transfer and more.

1. API Authentication and Authorization methods

API authentication and authorization methods are the most essential components of modern web and software development. These methods play a crucial role in ensuring the security and integrity of the data exchanged between systems and applications. 

Authentication verifies the identity of users or systems accessing an API, while authorization determines what actions or resources they are allowed to access. 

With a variety of techniques and protocols available, such as API keys, OAuth, and token-based systems, developers have the flexibility to choose the most suitable approach to protect their APIs and the data they manage.

Read our article on API Authentication Best Practices where we discuss top 5 authentication protocols such as OAuth, Bearer tokens, Basic auth, JWT and API keys in detail.

While choosing the right protocol depends on your specific use case and security requirements, here's a quick comparison of the 5 API authentication methods:

‍

Now, let’s explore how data can be transferred securely between API calls.

‍

2. Secure data transmission: Encryption and HTTPS

When it comes to API security, ensuring that data is transmitted securely is an absolute must. 

Imagine your data is like a confidential letter traveling from sender to receiver through the postal service. Just as you'd want that letter to be sealed in an envelope to prevent prying eyes from seeing its contents, data encryption in transit ensures that the information exchanged between clients and servers is kept safe and confidential during its journey across the internet. 

HTTPS

The go-to method for achieving this security is HTTPS, which is like the secure postal service for your data. 

HTTPS uses Transport Layer Security (TLS) or its predecessor, Secure Sockets Layer (SSL), to encrypt data before it leaves the sender's location and decrypt it only when it reaches the intended recipient. 

Think of TLS/SSL certificates as the unique stamps on your sealed letter; they ensure that the data's journey is tamper-proof and that it's delivered only to the right address. 

So, whenever you see that little padlock icon in your browser's address bar, rest assured that your data is traveling securely, just like that confidential letter in its sealed envelope.

In a world where data breaches are a constant threat, secure data transmission is like the lock and key that keeps your digital communication safe from potential eavesdroppers.

Note: As an API aggregator, Knit, prioritizes user privacy and commit to keeping your data safe in the best way possible. All data at Knit is doubly encrypted at rest with AES 256 bit encryption and in transit with TLS 1.3. Plus, all PII and user credentials are encrypted with an additional layer of application security. Learn more about Knit's security practices here 

‍

3. Input validation and parameter sanitization

In the world of API security, one area that often flies under the radar but is absolutely critical is input validation and parameter sanitization. It's like inspecting every ingredient that goes into a recipe; if you miss something harmful, the entire dish could turn out toxic.

First, let's talk about the risks. 

Input validation failures can open the door to a variety of malicious attacks, with one of the most notorious being injection attacks. 

These crafty attacks involve malicious code or data being injected into an API's input fields, exploiting vulnerabilities and wreaking havoc. Two common types are SQL injection and Cross-Site Scripting (XSS), both of which can lead to data breaches and system compromise. 

To learn more about injection vulnerabilities, read Common API Security Threats Developers Must Know About

How to defend against injection attacks 

Well, think of sanitizing user inputs as thoroughly washing your hands before handling food – it's a fundamental hygiene practice.

By rigorously examining and cleaning incoming data, we can block malicious code from getting through. For instance, when dealing with user-generated content, we should sanitize inputs to remove potentially harmful scripts or queries.

Additionally, for database queries, you should use parameterized statements instead of injecting user inputs directly into SQL queries. This way, even if an attacker tries a SQL injection, their input gets treated as data rather than executable code.

In the above example, we use a parameterized statement (? as a placeholder) to safely handle user input, preventing SQL injection by treating the input as data rather than executable SQL code.

In essence, input validation and parameter sanitization are like the gatekeepers of your API, filtering out the bad actors and ensuring the safety of your system. It's not just good practice; it's a crucial line of defense in the world of API security.

‍

4. Rate limiting and Throttling

Both rate limiting and throttling are critical components of API security, as they help maintain the availability and performance of API services, protect them against abusive usage, and ensure a fair distribution of resources among clients. 

Rate limiting restricts the number of API requests a client can make within a specific timeframe (e.g. requests per second or minute) while throttling is a more flexible approach that slows down or delays the processing of requests from clients who exceeded their allotted rate limit instead of denying requests outright. 

Throttling is useful for ensuring a more graceful degradation of service and a smoother user experience when rate limits are exceeded. The exhaustion of rate limits are often denoted by HTTP error code 429.

These techniques are often implemented in combination with each other to create a comprehensive defense strategy for APIs.

Read: 10 API rate limiting best practices to deal with HTTP error code 429

‍

5. API monitoring and logging

API monitoring and logging are vital for proactive security measures, threat detection, and incident response. 

API monitoring involves the continuous observation of API traffic and activities in real-time. It allows for immediate detection of unusual or suspicious behavior, such as spikes in traffic or unexpected access patterns. Beyond security, it also aids in optimizing performance by identifying bottlenecks, latency issues, or errors in API responses, ensuring smooth and efficient operation. 

API logging involves the recording of all API interactions and events over time. This creates a detailed historical record that can be invaluable for forensic analysis, compliance, and auditing. They are invaluable for debugging and troubleshooting, as they contain detailed information about API requests, responses, errors, and performance metrics. 

Monitoring and logging systems can also trigger alerts or notifications when predefined security thresholds are breached, enabling rapid incident response.

Access Logs and Issues in one page

This is exactly what Knit does.Alongside giving you access to 100+ HRIS, ATS, CRM, and other SaaS platformsthrough a single unified API, Knit also takes care of API logging andmonitoring for every connected integration.

Knit's Logs and Issues pagegives you a one-page historical overview of all your webhooks and integratedaccounts, including a count of API calls and filters to narrow down by platform, account, or time range. This helps you stay on top of integration healthwithout building separate logging for each platform you support.

For a deeper look at what tolog, where logs are stored, and the tools teams commonly use, see Knit's guideto API Monitoring and Logging.

‍

‍

6. Regular security audits and Penetration Testing

Regular security audits and penetration testing are critical components of a comprehensive API security strategy. They help identify vulnerabilities, assess the effectiveness of existing security measures, and ensure that an API remains resilient to evolving threats.

• ‍Security audits involve a thorough review of an API's design, architecture, and implementation to identify security weaknesses, misconfigurations, and best practice violations, and assess whether an API adheres to security policies, standards, and regulatory requirements. This is also important for ensuring compliance with data protection laws and industry regulations.

• Meanwhile Penetration testing, or pen testing, involves simulating cyberattacks to identify vulnerabilities, weaknesses, and potential entry points that malicious actors could exploit. It ​​attempt to exploit API vulnerabilities in a controlled environment to assess the API's resilience against real-world threats, including SQL injection, cross-site scripting (XSS), and more.

The results of penetration testing provide insights into the API's security posture, allowing organizations to prioritize and remediate high-risk vulnerabilities. Penetration tests should be conducted regularly, especially when changes or updates are made to the API, to ensure that security measures remain effective over time.

These practices are essential for safeguarding sensitive data and ensuring the trustworthiness of API-based services.

‍

7. API lifecycle management and decommissioning

A comprehensive approach to API security involves not only establishing APIs securely but also systematically retiring and decommissioning them when they are no longer needed or viable. 

This process involves clearly documenting the API's purpose, usage, and dependencies from the outset to facilitate informed decisions during the decommissioning phase. Also, you should implement version control and deprecation policies, enabling a gradual transition for API consumers and regularly audit and monitor API usage and access controls to detect potential security risks. 

When decommissioning an API, the sunset plan should be communicated with stakeholders while providing ample notice, and assistance to the users in migrating to alternative APIs or solutions.

Finally, a thorough security assessment and testing should be conducted before decommissioning to identify and resolve any vulnerabilities, to ensure that the process is executed securely and without compromising data or system integrity.

Read: Developer's guide to API lifecycle management

‍

8. Third-Party API Security Considerations

When integrating third-party APIs into your application, it's crucial to consider several important security factors. 

• First and foremost, thoroughly review the reputation and trustworthiness of the API provider. Assess their security practices and history of vulnerabilities. 

• Additionally, scrutinize the permissions and access levels you grant to the third-party API. Only provide the minimum access necessary for your application to function to limit potential risks. 

• Monitor the API's security updates and patch management, as vulnerabilities may emerge over time.

• Ensure that data transmitted between your application and the third-party API is encrypted and protected to safeguard against interception or tampering. 

• Lastly, have contingency plans in place for potential downtime or security breaches in the third-party API, which might affect your application's availability and data security.

These five checks — providerreputation, minimum necessary permissions, ongoing patch monitoring, encrypteddata in transit, and a contingency plan — are also the basis for the‘Third-party API review’ items in the checklist below.

‍

8. OWASP API Security Top 10: How These Practices Map

The OWASP API Security Top 10(2023) is the industry-standard framework for the most critical APIvulnerability categories, maintained by the Open Web Application SecurityProject. It's worth keeping on hand alongside the best practices above — here'show each category maps to the sections in this guide:

•        API1: Broken Object Level Authorization — occurs whenan API lets a user access or modify another user's data by changing an ID in arequest. Addressed by Section 1 (Authentication and Authorization methods),which covers verifying not just who a user is but what specific resourcesthey're allowed to touch.

•        API2: Broken Authentication — weak or missing checks ontokens, passwords, and API keys that let attackers compromise accounts.Addressed by Section 1.

•        API3: Broken Object Property Level Authorization — anAPI exposes or allows changes to data fields a client shouldn't see or edit,even if overall access is authorized. Addressed by Sections 1 and 3 (Inputvalidation and parameter sanitization), which limit what fields a request canread or write.

•        API4: Unrestricted Resource Consumption — an API withno limits on request frequency, payload size, or processing cost, opening thedoor to denial-of-service issues and runaway costs. Addressed directly bySection 4 (Rate limiting and Throttling).

•        API5: Broken Function Level Authorization —access-control gaps that let regular users reach administrative or privilegedendpoints. Addressed by Section 1.

•        API6: Unrestricted Access to Sensitive Business Flows —an API exposes a multi-step business process (like checkout or accountcreation) without checks on whether a request is following the intended flow.Addressed by Section 6 (Regular security audits and Penetration Testing), wherethis kind of abuse is most reliably caught.

•        API7: Server-Side Request Forgery (SSRF) — an APIaccepts a user-supplied URL and fetches it without validating the destination,letting an attacker reach internal systems. Addressed by Sections 2 and 3,which cover validating and sanitizing everything an API sends or receives.

•        API8: Security Misconfiguration — open storage, verboseerror messages, missing security headers, or overly permissive CORS settings.Addressed by Section 2 (Encryption and HTTPS) and Section 6 (audits).

•        API9: Improper Inventory Management — undocumented,deprecated, or debug API versions left exposed. Addressed directly by Section 7(API lifecycle management and decommissioning).

•        API10: Unsafe Consumption of APIs — trusting data froma third-party API without validating it, so a compromised upstream APIcompromises you too. Addressed directly by Section 8 (Third-Party API SecurityConsiderations).

For the full detail behind eachcategory, including real-world examples, the OWASP API Security Projectmaintains the authoritative reference at owasp.org. Use the list above as aquick cross-check against the best practices in this guide — if a section abovefeels thin for your use case, the corresponding OWASP category is a good placeto dig deeper.

‍

API security checklist

Use this checklist as a workingreference when building, reviewing, or integrating with APIs. It follows thesame structure as the best practices above — and maps to the OWASP API SecurityTop 10 categories covered in the previous section.

Authentication and authorization

•        Use a standard protocol (OAuth 2.0, API keys, or JWTs)appropriate to your use case

•        Issue short-lived access tokens with refresh tokensrather than long-lived credentials

•        Scope tokens and API keys to the minimum permissionsneeded

•        Check authorization on every request, not just at login

Encryption and transport security

•        Enforce HTTPS (TLS 1.2+) on every endpoint — noplaintext HTTP

•        Encrypt sensitive data at rest, in addition to intransit

•        Set security headers and restrict CORS to known origins

Input validation and sanitization

•        Validate and sanitize every input field, includingheaders and query parameters

•        Use parameterized queries for all database access —never concatenate user input into SQL

•        Restrict which object fields a request can read orwrite (avoid mass-assignment issues)

Rate limiting and throttling

•        Set per-client rate limits based on API key, token, orIP

•        Return HTTP 429 with a Retry-After header when limitsare exceeded

•        Tier limits by endpoint cost and client type

Monitoring and logging

•        Log every request and response, including timestamps,status codes, and caller identity

•        Set alerts for unusual traffic patterns or spikes inerrors

•        Retain logs long enough to support debugging, audits,and incident response

Lifecycle management

•        Document each API version's purpose, usage, anddependencies

•        Apply version control and deprecation policies withadvance notice to consumers

•        Conduct a security review before decommissioning anyAPI

Third-party API review

•        Vet the security track record and reputation of anythird-party API provider

•        Grant only the minimum access scopes the integrationneeds

•        Monitor third-party APIs for security updates andbreaking changes

•        Have a contingency plan for third-party API downtime ora security incident upstream

‍

To download checklist, click here

‍

Common API security FAQs by developers

What is the OWASP API Security Top 10?

The OWASP API Security Top 10 is the industry-standard list of the most critical security risks specific to APIs, maintained by the Open Web Application Security Project and most recently updated in 2023. It covers risks such as Broken Object Level Authorization, Broken Authentication, Unrestricted Resource Consumption, Server-Side RequestForgery, and Unsafe Consumption of APIs, among others. Unlike the general OWASP Top 10, which focuses on web application vulnerabilities broadly, this list addresses issues unique to how APIs expose data and business logic throughendpoints. The best practices in this guide map directly to each of these tencategories — see the OWASP API Security Top 10 section above for the full mapping. Reviewing your APIs against this list is one of the most efficientways to prioritize security work.

What are the most common API security risks?

The most common API security risks include unauthorized access from weak or broken authentication, injection attacks such as SQL injection and cross-site scripting, excessive data exposure through endpoints that return more information than needed, lack of rate limiting that leaves APIs open to abuse, and security misconfigurations such as missing headers or overly verbose error messages. Third-party dependencies and human error round out the list — a vulnerability in an API you integrate with, or a single misconfigured permission, can compromise your application even if your own code is otherwise secure. This guide's section on API security risks covers each of these in more depth. Addressing them systematically, using the OWASP API Security Top 10 as a checklist, is the most reliable way to reduce your API's attack surface.

What should be on an API security checklist?

A solid API security checklistcovers six areas: authentication and authorization (strong protocols,short-lived tokens, least-privilege scopes), encryption (HTTPS/TLS for alltraffic and encryption at rest), input validation (sanitizing every parameter andusing parameterized queries), rate limiting (per-client limits with HTTP 429responses), monitoring and logging (recording every request, response, anderror), and third-party API review (vetting providers and limiting the accessyou grant them). The full checklist earlier in this guide breaks each area intospecific, actionable items. Knit handles several of these — encryption,logging, and monitoring — automatically for every one of the 100+ platforms itconnects, which is useful if your checklist spans many integrations rather thana single API.

What's the difference between the OWASP Top 10 and the OWASP API SecurityTop 10?

The OWASP Top 10 is a broad listof the most critical risks to web applications generally, covering issues like injection, broken access control, and security misconfiguration across any type of application. The OWASP API Security Top 10 is a separate, API-specific listthat focuses on risks unique to how APIs expose data and functionality through endpoints — such as Broken Object Level Authorization, where an API lets a user access another user's data by changing an ID in a request, or Unrestricted ResourceConsumption, where an API has no limits on request volume or payload size. If you're building or securing APIs specifically, the API Security Top 10 is the more directly applicable framework, though both lists are maintained by OWASP and complement each other.

What are API authentication best practices?

Strong API authentication startswith choosing the right protocol for the job — OAuth 2.0 for delegated access,API keys for simple server-to-server calls, or JWTs for stateless sessionvalidation — and applying it consistently. From there, best practices includeissuing short-lived access tokens with refresh tokens rather than long-livedcredentials, scoping tokens to the minimum permissions needed, and rotating APIkeys regularly. Authorization should be checked on every request, not just atlogin, to avoid the broken object- and function-level access issues covered inthe OWASP mapping above. For teams managing authentication across manythird-party APIs rather than just their own, Knit handles OAuth flows, tokenrefresh, and credential storage for every connected platform, removing a commonsource of authentication-related security gaps.

What are rate limiting best practices for REST APIs?

Effective rate limiting startswith setting per-client limits based on an API key, token, or IP address, andreturning an HTTP 429 (Too Many Requests) response with a Retry-After headerwhen a client exceeds them. Many APIs combine hard limits with throttling —slowing requests down rather than rejecting them outright — so the servicedegrades gracefully under load instead of failing. Limits should be tiered byendpoint cost and client type, and logging rate-limit events helps identifyclients that need higher limits or are misbehaving. Knit's guide to API ratelimiting and throttling covers these patterns in more detail, including how tohandle 429 responses when integrating with third-party APIs that enforce theirown limits.

How does Knit keep API integrations secure?

Knit secures every integrationwith AES-256 encryption at rest and TLS 1.3 in transit, with an additionallayer of encryption for PII and user credentials. Beyond encryption, Knit isSOC2, GDPR, and ISO27001 certified, and its infrastructure is continuouslymonitored with intrusion detection systems backed by a 24/7 support team. Forteams evaluating third-party APIs as part of their own security review — arecurring theme in the checklist above — Knit's security practices aredocumented in full at getknit.dev/security, making it straightforward toinclude in a vendor security assessment.

Does Knit store or share end-user data with third parties?

No. Knit is built as apass-through proxy and does not store a copy of your end users' data on itsservers or share it with any third party. Data is processed in Knit'sapplication server and sent directly to your webhooks via event-based syncs,rather than being retained in a database. This directly addresses one of thebiggest third-party API security concerns covered in this guide — that avendor's data retention practices could expose your users' data even if yourown systems are secure. For security-conscious teams, this no-data-copyarchitecture removes an entire category of risk from the third-party API reviewchecklist.

Have a question that isn'tcovered here? Read all the FAQs in Knit's dedicated post on common API securityFAQs.

Enable maximum security for your API integrations with Knit

If you are dealing with a large number of API integrations and looking for smarter solutions, check out unified API solutions like Knit. Knit ensures that you have access to high quality data faster in the safest way possible.

• Knit is the only unified API in the market that does NOT store a copy of your end user data in its servers or share it with any third party. All of our syncs are event-based and happen via webhooks to ensure that your data is not subjected to any external threats during the transfer. Learn more about Knit's secure data sync here

• Knit complies with industry best practices and security standards. We are SOC2, GDPR and ISO27001 certified and always in the process of adding more security badges to our collection.

• We monitor Knit's infrastructure continuously with the finest intrusion detection systems. Plus, our super responsive support team is available 24*7 across all time zones to make sure if at all a security issue occurs, it is resolved immediately.

We understand how crucial your data is. That's why we are always fine-tuning our security measures to offer maximum protection for your user data.  Talk to one of our experts to learn more. If you are ready to build integrations at scale, get your API keys for free

API logging is the practice of recording every request and response that passes through yourAPI — including timestamps, status codes, and identifying details — so you have a complete,searchable history of what happened and when. Pair that with monitoring, which watches thisactivity in real time, and you get both the early-warning system and the audit trail you need tokeep an API reliable and secure.This guide covers what API logging is, what to capture, where logs typically live, the tools teamsuse, how monitoring builds on logging, and how Knit gives you a single logging and monitoringview across every third-party API your product connects to.

‍

TABLE OF CONTENTS

•        What Is API Logging?

•        What to Log: Key Data Points for Effective API Logs

•        Where API Logs Are Stored

•        API Logging Tools and Examples

•        API Monitoring: How It Builds on Logging

•        How Knit Centralizes Logging and Monitoring Across YourIntegrations

•        FAQs

‍

What Is API Logging?

API logging is the process ofrecording details about every request made to an API and every response itreturns. Each log entry typically captures the endpoint called, the HTTPmethod, a timestamp, the response status code, the identity of the caller, andhow long the request took to process.

Think of it as a diary for yourAPI: every time a client calls an endpoint, a log entry records who did what,when, and what happened as a result. Over time, these entries build asearchable history you can use to debug a failed request from last week, demonstratecompliance during an audit, spot a client that's hitting rate limits, orunderstand which endpoints get the most traffic.

API logging is distinct from APImonitoring, which is about watching that activity in real time and reacting toit — covered later in this guide. Logging is the record; monitoring is theresponse.

‍

What to Log: Key Data Points for Effective API Logs

‍

Not all logging is usefullogging. A log entry that just says “request received” tells you little whenyou’re debugging an incident at 2am. At minimum, an API log entry shouldcapture:

•        Timestamp — when the request was received and when theresponse was sent, which also gives you latency

•        Endpoint and HTTP method — which resource was calledand how (GET, POST, PATCH, DELETE, etc.)

•        Request and response status codes — 200, 401, 404, 429,500, and so on, the fastest way to spot patterns of failure

•        Caller identity — an API key, user ID, or client ID(not raw credentials), so you can trace activity back to a specific integrationor user

•        IP address and user agent — useful for spotting unusualaccess patterns or abuse

•        Request and response size and latency — helps identifyslow endpoints or oversized payloads

•        Error details — for failed requests, the error code anda human-readable message, not just a stack trace

One important best practice:never log sensitive data in plain text. Passwords, API secrets, access tokens,and personally identifiable information such as full names, emails, or paymentdetails should be masked or excluded entirely — logs are often retained formonths and accessed by more people than the production database.

Finally, decide on retention upfront. Many teams keep detailed logs for 30–90 days for debugging, then roll upto aggregated metrics — request counts, error rates — for longer-term trendanalysis. This keeps storage costs predictable while still preserving thehistory you need.

‍

Where API Logs Are Stored

‍

Where API logs live depends on the size and maturity of your setup. The three most common options:

•        Application-level log files — the simplest approach:your API writes structured log lines, often as JSON, to stdout or a file. Thisworks fine for small services or local development but doesn’t scale well forsearching across many instances.

•        Centralized log management platforms — tools like theELK stack (Elasticsearch, Logstash, Kibana), Grafana Loki, Datadog, or Splunkaggregate logs from every instance of your API into one searchable system, withdashboards, alerts, and retention policies built in. This is the standardapproach for production APIs at any meaningful scale.

•        Cloud-native logging services — if your API runs on AWS, Google Cloud, or Azure, services like Amazon CloudWatch Logs, Google Cloud Logging, or Azure Monitor Logs capture logs automatically from yourinfrastructure with minimal setup and integrate with the rest of each cloud’s monitoring stack.

Most teams start withapplication-level logs during development, then move to a centralized orcloud-native platform once the API is in production and logs need to besearched, correlated, and alerted on across multiple services.

‍

API Logging Tools and Examples

‍

The right logging tool dependson your stack and budget. Broadly, tools fall into a few categories:

•        Open-source log aggregation — the ELK stack and GrafanaLoki are widely used, self-hosted options that give you full control overstorage and retention, at the cost of running and maintaining theinfrastructure yourself.

•        API-focused observability platforms — tools like Moesif and New Relic are built specifically around API traffic, with features like per-endpoint analytics, error-rate tracking, and customer-level usage breakdowns alongside raw logs.

•        General application monitoring platforms — Datadog,Splunk, and similar platforms cover API logs as part of a broader observabilitystack that also includes infrastructure metrics, traces, and alerting.

•        Cloud provider tools — AWS, Google Cloud, and Azure allinclude native logging (CloudWatch, Cloud Logging, Azure Monitor) that requireslittle setup if you’re already running on that cloud.

A simple API log entry, in JSON,might look like:

{
  "timestamp": "2026-06-11T10:32:01Z",
  "method": "GET",
  "endpoint": "/v1/contacts",
  "status": 200,
  "client_id": "acct_8821",
  "latency_ms": 142
}

That single entry — timestamp,method, endpoint, status, caller, and latency — is enough to answer most “whathappened and when” questions, and is the basis most logging tools builddashboards and alerts on top of.

Why do you need to monitor your APIs regularly

Real-time monitoring provides an extra layer of protection by actively watching API traffic for any anomalies or suspicious patterns.

For instance - 

• It can spot a sudden surge in requests from a single IP address, which could be a sign of a distributed denial-of-service (DDoS) attack. 
• It can also detect multiple failed login attempts in quick succession, indicating a potential brute-force attack. 

In both cases, real-time monitoring can trigger alerts or automated responses, helping you take immediate action to safeguard your API and data.

API Logging

Now, on similar lines, imagine having a detailed diary of every interaction and event within your home, from visitors to when and how they entered. Logging mechanisms in API security serve a similar purpose - they provide a detailed record of API activities, serving as a digital trail of events.

Logging is not just about compliance; it's about visibility and accountability. By implementing logging, you create a historical archive of who accessed your API, what they did, and when they did it. This not only helps you trace back and investigate incidents but also aids in understanding usage patterns and identifying potential vulnerabilities.

To ensure robust API security, your logging mechanisms should capture a wide range of information, including request and response data, user identities, IP addresses, timestamps, and error messages. This data can be invaluable for forensic analysis and incident response. 

API Monitoring: How It Builds on Logging

Where logging gives you a recordof what happened, monitoring watches that activity as it happens and flagsanything unusual. Real-time monitoring can, for example:

•        Spot a sudden surge in requests from a single client,which could indicate a denial-of-service attempt or a runaway integration

•        Detect repeated authentication failures in quicksuccession, which often signals a brute-force attempt or a misconfigured client

•        Alert when error rates or latency for a specificendpoint spike - often the first sign of a deployment issue or a downstreamoutage

When monitoring flags something,your logs provide the context: what request triggered it, who made it, and whathappened immediately before and after. Logging without monitoring means youhave the history but may find out about problems too late; monitoring withoutlogging gives you an alert but no record to investigate it with. Mostproduction APIs need both.

‍

How Knit Centralizes Logging and MonitoringAcross Your Integrations

Implementing the kind of loggingand monitoring described above is straightforward for one API. It gets harderwhen your product connects to dozens of third-party platforms — each with itsown auth, rate limits, and failure modes — and you need visibility across allof them.

This is where Knit’s Logs andIssues page comes in. Knit’s Unified API connects your product to 100+ HRIS,ATS, CRM, and other SaaS platforms through a single integration, and gives youone page that shows the history of every API call, webhook, and integratedaccount across all of them — with filters so you can drill into a specificcustomer, platform, or time range. Instead of building separate logging andmonitoring for each integration, you get one consolidated view from day one.

For platforms that don’t supportreal-time webhooks natively, Knit’s virtual webhooks deliver normalized changeevents to your application, so you’re not relying on logs alone to know whensomething changes upstream.

‍

Want one view of logging and monitoring across every integration your product supports? Sign up for free andexplore Knit’s Logs and Issues page for yourself.

‍

FAQs

What is a logging API / what are API logs?

API logs are records of everyrequest and response that pass through an API, including the endpoint called,the HTTP method, timestamps, status codes, and the identity of the caller.Knit's Unified API generates this kind of log data automatically for everyconnected integration, surfacing it in a single Logs and Issues page ratherthan requiring you to build logging for each platform separately. A typical logentry might record that a GET request to /v1/contacts returned a 200 status in142ms for a specific client ID. Over time, these entries form a searchablehistory that teams use to debug failed requests, demonstrate compliance duringaudits, and understand usage patterns across their own API and the third-partyAPIs they depend on.

Where are API logs stored?

API logs are typically stored in one of three places: application-level log files for small or early-stageservices, centralized log management platforms such as the ELK stack, GrafanaLoki, or Datadog for production APIs at scale, and cloud-native loggingservices such as AWS CloudWatch Logs or Google Cloud Logging for APIs runningon those platforms. For teams managing logs across many third-partyintegrations rather than a single API, Knit's Logs and Issues page stores andsurfaces this history in one place automatically, covering every connectedplatform without separate log infrastructure per integration. Most teams startwith application-level logs during development and move to a centralized orcloud-native platform once logs need to be searched and correlated acrossservices.

What should you log from an API call?

At minimum, log the timestamp,endpoint, HTTP method, request and response status codes, caller identity suchas an API key or client ID, latency, and error details for failed requests.These fields are usually enough to answer most debugging questions: whathappened, when, to whom, and how long it took. Avoid logging sensitive datasuch as passwords, access tokens, or personally identifiable information inplain text, since logs are often retained for months and accessed more broadlythan production databases. If your product integrates with multiple third-partyAPIs, Knit's Unified API captures this level of detail for every connectedplatform automatically, so your team doesn't need to instrument loggingseparately for each integration you support.

What's the difference between API logging and API monitoring?

API logging is the practice ofrecording what happened — every request, response, status code, and timestamp —building a historical record you can search later. API monitoring is watchingthat activity in real time and reacting to it, for example alerting when errorrates spike or when an unusual surge in requests suggests a problem. Loggingwithout monitoring means you have the history but may not notice an issue untilsomeone looks for it; monitoring without logging gives you an alert but norecord to investigate. Knit combines both for the integrations it connects: itsLogs and Issues page gives you the historical record, while virtual webhookssurface real-time change events for platforms that don't support webhooksnatively, so you get visibility and alerts together.

What are some API logging best practices?

Good API logging practicesinclude capturing a consistent set of fields on every request — timestamp,endpoint, method, status code, caller identity, and latency — using astructured format like JSON so logs are easy to search and parse. Mask orexclude sensitive data such as passwords, tokens, and personal informationrather than logging it in plain text. Set a retention policy up front, forexample keeping detailed logs for 30-90 days and rolling up to aggregatedmetrics afterward to control storage costs. For teams supporting manythird-party integrations, Knit applies this kind of structured, consistentlogging automatically across every connected platform, so individual teamsdon't need to define and maintain their own logging standards per integration.

What tools are commonly used for API logging?

Common API logging tools fall into a few categories: open-source log aggregation platforms like the ELK stack and Grafana Loki, API-focused observability tools like Moesif and New Relic, broader application monitoring platforms like Datadog and Splunk, and cloud-native logging services such as AWS CloudWatch Logs, Google Cloud Logging, and Azure Monitor. Which one fits depends on your stack, scale, andwhether you need API-specific analytics or broader infrastructure monitoring alongside logs. If the logging you need is for third-party APIs your productconnects to rather than your own API, Knit's Logs and Issues page provides thisview natively across 100+ connected platforms, without requiring you to wire up a separate logging tool for each one.

How does Knit help teams monitor and log API integrations?

Knit gives teams a single Logsand Issues page that shows the history of every API call, webhook, andintegrated account across all the platforms connected through Knit's UnifiedAPI — currently 100+ HRIS, ATS, CRM, and other SaaS tools. Instead of buildingseparate logging for each integration your product supports, you get oneconsolidated, filterable view from day one, covering specific customers,platforms, or time ranges. This is particularly useful for SaaS products thatsupport many customer-facing integrations, where debugging “why didn’t thissync” questions across dozens of platforms would otherwise mean checking dozensof different logging systems.

Does Knit provide real-time alerts or webhooks for integration issues?

Yes. Knit provides virtualwebhooks that deliver normalized, real-time change events from connectedplatforms, including ones that don't support outbound webhooks natively — Knithandles the underlying polling and delivers a consistent event format to yourapplication either way. Combined with the Logs and Issues page, this means yourteam gets both a real-time signal when something changes or fails upstream, anda searchable historical record to investigate it. For products that depend ondozens of third-party integrations staying in sync, this removes the need tobuild custom monitoring and polling logic for each platform individually.

‍

Building a ServiceNow integration is fundamentally different from every other API integration you've built — because there is no single ServiceNow. Every customer runs their own instance at a unique subdomain, with their own OAuth endpoints, their own permission model, and their own table customisations. Guides written for ServiceNow developers working inside an instance won't help you. This one is written for developers building a product that connects to their customers' ServiceNow instances.

Quick answer: Use the Table API (/api/now/table/{tableName}) for reading and writing incidents, users, groups, and requests. Authenticate via OAuth 2.0 — but collect the customer's instance URL first, since every OAuth endpoint is instance-specific. The five tables that cover 90% of ITSM product integration use cases are incident, sys_user, sys_user_group, sc_request, and change_request.

This guide covers per-instance OAuth setup, Table API endpoints and query syntax, webhook configuration, rate limits, and three real-world integration patterns with working code — all from the perspective of an external developer connecting to a customer's ServiceNow instance.

If your product needs to support ServiceNow alongside other ITSM tools like Jira, Zendesk, or GitHub Issues, there's a unified approach worth knowing about — covered in the Building with Knit section.

The ServiceNow API: Table API, Scripted REST, and Import Sets

ServiceNow exposes several API surfaces. The right one for your integration depends on what you're doing:

The Table API is the right choice for the vast majority of product integrations. It provides CRUD access to any ServiceNow table through a consistent URL pattern:

https://{instance}.service-now.com/api/now/table/{tableName}

The Scripted REST API requires a ServiceNow developer to create custom endpoints inside the instance — you can't deploy these from outside. The Import Set API is for bulk historical data loads, not real-time integrations.

Authentication: Per-Instance OAuth and Why It's Different

ServiceNow OAuth is standard OAuth 2.0 in mechanics, but the endpoints are not standard — they're instance-specific. This is the detail that trips most developers up when building a multi-tenant integration.

For a typical API (Slack, GitHub, HubSpot), you hardcode a single OAuth endpoint:

https://slack.com/api/oauth.v2.access

For ServiceNow, every customer has their own:

https://{customer-instance}.service-now.com/oauth_token.do
https://{customer-instance}.service-now.com/oauth_auth.do

This means your integration must:

1. Collect the customer's ServiceNow instance URL before initiating OAuth
2. Construct the OAuth endpoints dynamically per customer
3. Store per-customer OAuth credentials (access token, refresh token, instance URL)
4. Handle token refresh per customer independently

Here's what that looks like in practice:

Step 1: Collect the Instance URL

Your onboarding UI needs to ask for the instance identifier — the [company] part of https://[company].service-now.com. This is what Knit's auth screen shows users when they connect ServiceNow.

def get_servicenow_endpoints(instance: str) -> dict:
    """
    Build instance-specific OAuth endpoints from the instance identifier.
    instance = "mycompany" (not the full URL)
    """
    base = f"https://{instance}.service-now.com"
    return {
        "base_url": base,
        "auth_url": f"{base}/oauth_auth.do",
        "token_url": f"{base}/oauth_token.do",
        "api_base": f"{base}/api/now/table"
    }

Step 2: Register an OAuth Provider in ServiceNow

Before any OAuth flow can happen, the customer's ServiceNow admin must register your application as an OAuth provider in their instance: System OAuth > Application Registry > New > Create an OAuth API endpoint for external clients.

Required fields:

• Name: Your application name
• Client ID: Auto-generated (give this to the customer)
• Client Secret: Auto-generated (store securely)
• Redirect URL: Your callback URL

This is a one-time admin step per customer instance. Document it clearly in your onboarding instructions.

Step 3: OAuth Authorization Flow

import requests
from urllib.parse import urlencode

def get_auth_url(instance: str, client_id: str, redirect_uri: str, state: str) -> str:
    """Redirect the customer's admin to this URL to initiate OAuth consent."""
    endpoints = get_servicenow_endpoints(instance)
    params = {
        "response_type": "code",
        "client_id": client_id,
        "redirect_uri": redirect_uri,
        "state": state  # CSRF protection — always validate on callback
    }
    return f"{endpoints['auth_url']}?{urlencode(params)}"


def exchange_code_for_tokens(instance: str, client_id: str, client_secret: str,
                              code: str, redirect_uri: str) -> dict:
    """Exchange the authorization code for access + refresh tokens."""
    endpoints = get_servicenow_endpoints(instance)
    response = requests.post(
        endpoints["token_url"],
        data={
            "grant_type": "authorization_code",
            "code": code,
            "redirect_uri": redirect_uri,
            "client_id": client_id,
            "client_secret": client_secret
        }
    )
    response.raise_for_status()
    tokens = response.json()
    # Store tokens["access_token"], tokens["refresh_token"], and instance per customer
    return tokens

Step 4: Token Refresh

ServiceNow access tokens expire after 30 minutes by default (configurable by the admin). Build refresh logic before you hit your first expiry:

def refresh_access_token(instance: str, client_id: str, client_secret: str,
                          refresh_token: str) -> dict:
    endpoints = get_servicenow_endpoints(instance)
    response = requests.post(
        endpoints["token_url"],
        data={
            "grant_type": "refresh_token",
            "client_secret": client_secret,
            "client_id": client_id,
            "refresh_token": refresh_token
        }
    )
    response.raise_for_status()
    return response.json()  # New access_token and refresh_token

If you're building a product that integrates with ServiceNow alongside other ITSM tools — Jira, Zendesk, GitHub, Linear — building and maintaining per-instance OAuth for each one is significant infrastructure overhead. Knit handles ServiceNow's instance URL collection and OAuth flow per customer, so you get a single integration layer across all your supported tools. → getknit.dev/integration/servicenow

Key Table API Endpoints and the Five Tables That Matter

The Tables

ServiceNow has hundreds of tables. For a B2B product integration, these five cover the vast majority of use cases:

All Table API requests follow the same pattern:

GET https://{instance}.service-now.com/api/now/table/{table}
Authorization: Bearer {access_token}
Accept: application/json
Content-Type: application/json
X-no-response-body: false

The sysparm Parameters

ServiceNow's Table API uses sysparm_ prefixed query parameters for filtering, field selection, and pagination. Understanding these is essential — without them you'll either pull the entire table or struggle with pagination.

Reading Incidents

def get_incidents(instance: str, token: str,
                  state: str = None, assigned_to: str = None,
                  limit: int = 100, offset: int = 0) -> dict:
    """
    Fetch incidents from a ServiceNow instance.
    state codes: 1=New, 2=In Progress, 3=On Hold, 6=Resolved, 7=Closed
    """
    query_parts = []
    if state:
        query_parts.append(f"state={state}")
    if assigned_to:
        query_parts.append(f"assigned_to.user_name={assigned_to}")

    params = {
        "sysparm_limit": limit,
        "sysparm_offset": offset,
        "sysparm_fields": "sys_id,number,short_description,description,state,"
                          "priority,assigned_to,assignment_group,opened_at,"
                          "resolved_at,sys_created_on,sys_updated_on",
        "sysparm_exclude_reference_link": "true",
        "sysparm_display_value": "false"  # Raw values are easier to work with
    }
    if query_parts:
        params["sysparm_query"] = "^".join(query_parts)

    response = requests.get(
        f"https://{instance}.service-now.com/api/now/table/incident",
        headers={
            "Authorization": f"Bearer {token}",
            "Accept": "application/json"
        },
        params=params
    )
    response.raise_for_status()

    # Pagination: check X-Total-Count header for total record count
    total = int(response.headers.get("X-Total-Count", 0))
    return {
        "records": response.json()["result"],
        "total": total,
        "has_more": (offset + limit) < total
    }

Creating an Incident

def create_incident(instance: str, token: str,
                    short_description: str, description: str,
                    caller_id: str = None, priority: int = 3,
                    assignment_group: str = None) -> dict:
    """
    Creates an incident. Priority: 1=Critical, 2=High, 3=Moderate, 4=Low.
    caller_id and assignment_group are sys_id values from sys_user/sys_user_group.
    """
    payload = {
        "short_description": short_description,
        "description": description,
        "priority": str(priority),
        "impact": str(priority),    # Often mirrors priority
        "urgency": str(priority)
    }
    if caller_id:
        payload["caller_id"] = caller_id
    if assignment_group:
        payload["assignment_group"] = assignment_group

    response = requests.post(
        f"https://{instance}.service-now.com/api/now/table/incident",
        headers={
            "Authorization": f"Bearer {token}",
            "Accept": "application/json",
            "Content-Type": "application/json"
        },
        json=payload
    )
    response.raise_for_status()
    result = response.json()["result"]
    return {
        "sys_id": result["sys_id"],       # Use this for future updates
        "number": result["number"],        # Human-readable e.g. INC0012345
        "state": result["state"],
        "url": f"https://{instance}.service-now.com/nav_to.do?uri=incident.do?sys_id={result['sys_id']}"
    }

Updating an Incident

def update_incident(instance: str, token: str,
                    sys_id: str, **fields) -> dict:
    """
    Update any incident fields by sys_id.
    Common fields: state, assigned_to, assignment_group, work_notes, close_notes
    """
    response = requests.patch(
        f"https://{instance}.service-now.com/api/now/table/incident/{sys_id}",
        headers={
            "Authorization": f"Bearer {token}",
            "Accept": "application/json",
            "Content-Type": "application/json"
        },
        json=fields
    )
    response.raise_for_status()
    return response.json()["result"]

Users and Groups

# Get a user by their email address (common lookup pattern)
def get_user_by_email(instance: str, token: str, email: str) -> dict | None:
    response = requests.get(
        f"https://{instance}.service-now.com/api/now/table/sys_user",
        headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
        params={
            "sysparm_query": f"email={email}^active=true",
            "sysparm_fields": "sys_id,name,email,user_name",
            "sysparm_limit": 1,
            "sysparm_exclude_reference_link": "true"
        }
    )
    response.raise_for_status()
    results = response.json()["result"]
    return results[0] if results else None

# List all active groups
def list_groups(instance: str, token: str) -> list:
    response = requests.get(
        f"https://{instance}.service-now.com/api/now/table/sys_user_group",
        headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
        params={
            "sysparm_query": "active=true",
            "sysparm_fields": "sys_id,name,description,manager",
            "sysparm_limit": 1000,
            "sysparm_exclude_reference_link": "true"
        }
    )
    response.raise_for_status()
    return response.json()["result"]

Webhooks: Business Rules and Outbound REST Messages

ServiceNow does not have native outbound webhooks that you configure from outside the instance. Real-time event notifications require a ServiceNow admin on the customer side to set up two things: a Business Rule (which triggers on record events) and an Outbound REST Message (which sends the payload to your server).

This is a key difference from APIs like GitHub or Slack where you register a webhook URL programmatically. For ServiceNow, you need to provide your customers' IT teams with setup instructions.

What the customer's admin configures:

Business Rule (System Definition > Business Rules):

• Table: incident
• When to run: after insert/update
• Condition: (whatever triggers the notification — e.g., state changes)
• Script:

// ServiceNow Business Rule script
var message = new sn_ws.RESTMessageV2('Your Integration', 'POST incident');
message.setStringParameterNoEscape('sys_id', current.sys_id);
message.setStringParameterNoEscape('number', current.number);
message.setStringParameterNoEscape('state', current.state);
message.setStringParameterNoEscape('updated_at', current.sys_updated_on);
var response = message.execute();

Outbound REST Message (System Web Services > Outbound > REST Message):

• Endpoint: your server's webhook URL
• HTTP Method: POST
• Authentication: Basic or OAuth (your server's credentials)

On your server, receive and process the payload:

from flask import Flask, request, abort
import hmac, hashlib

app = Flask(__name__)

@app.route("/webhook/servicenow", methods=["POST"])
def handle_servicenow_event():
    # ServiceNow doesn't send a standard signature header —
    # secure your endpoint via IP allowlisting or a shared secret
    # passed as a query param or custom header agreed with the admin
    payload = request.json
    sys_id = payload.get("sys_id")
    state = payload.get("state")

    # State codes: 1=New, 2=In Progress, 3=On Hold, 6=Resolved, 7=Closed
    if state in ("6", "7"):
        close_linked_item_in_your_product(sys_id)

    return "", 200

Because webhook setup requires admin access on the customer's instance, build your integration to work without webhooks first (polling) and offer webhook setup as an enhancement for customers whose admins can configure it.

Rate Limits

ServiceNow rate limits are instance-configured, not globally fixed — your customer's IT admin controls them. This creates a situation you won't face with other APIs: two customers on the same plan can have different rate limits.

Unlike GitHub or Slack, ServiceNow does not return rate limit headers (X-RateLimit-Remaining etc.) on every response. You'll receive a 429 Too Many Requests when you hit the limit — build retry logic with exponential backoff:

import time

def servicenow_request(url: str, token: str, max_retries: int = 3, **kwargs) -> requests.Response:
    for attempt in range(max_retries):
        response = requests.get(url, headers={
            "Authorization": f"Bearer {token}",
            "Accept": "application/json"
        }, **kwargs)

        if response.status_code == 429:
            wait = 2 ** attempt * 10  # 10s, 20s, 40s
            time.sleep(wait)
            continue

        if response.status_code == 401:
            # Token likely expired — trigger refresh and retry once
            raise TokenExpiredError("Access token expired")

        response.raise_for_status()
        return response

    raise Exception(f"Max retries exceeded for {url}")

For sustained high-volume integrations, use a dedicated integration user account in ServiceNow rather than a human user's account — this ensures your rate limit isn't shared with the user's other API activity.

3 Common ServiceNow Integration Patterns

Pattern 1: Sync Incidents into Your Product

Pull all open incidents and keep them in sync with periodic polling:

def full_incident_sync(instance: str, token: str) -> list:
    """
    Full sync of all open and in-progress incidents.
    Run on initial connection; switch to delta sync (updatedAfter) for ongoing.
    """
    all_incidents = []
    offset = 0
    limit = 100

    while True:
        page = get_incidents(
            instance=instance,
            token=token,
            limit=limit,
            offset=offset
        )
        all_incidents.extend(page["records"])

        if not page["has_more"]:
            break
        offset += limit

    # Normalise ServiceNow state codes to your product's status model
    status_map = {
        "1": "open", "2": "in_progress", "3": "on_hold",
        "6": "resolved", "7": "closed"
    }

    return [
        {
            "external_id": i["sys_id"],
            "reference": i["number"],
            "title": i["short_description"],
            "status": status_map.get(str(i["state"]), "unknown"),
            "priority": i["priority"],
            "assignee_id": i.get("assigned_to"),
            "created_at": i["sys_created_on"],
            "updated_at": i["sys_updated_on"]
        }
        for i in all_incidents
    ]

Pattern 2: Create an Incident from Your Product

The common "escalate to IT" pattern — a user triggers an action in your product and it creates a ServiceNow incident:

Raw ServiceNow approach — you need to resolve the user's sys_id first, look up the right assignment group sys_id, then create the incident:

# Step 1: resolve caller sys_id from user's email
caller = get_user_by_email(instance, token, user_email)
caller_sys_id = caller["sys_id"] if caller else None

# Step 2: look up assignment group sys_id
groups = list_groups(instance, token)
group = next((g for g in groups if g["name"] == "IT Help Desk"), None)
group_sys_id = group["sys_id"] if group else None

# Step 3: create the incident
incident = create_incident(
    instance=instance,
    token=token,
    short_description=f"Alert from {your_product}: {alert_title}",
    description=alert_details,
    caller_id=caller_sys_id,
    assignment_group=group_sys_id,
    priority=2  # High
)
# Store incident["sys_id"] in your DB for future status sync

With Knit — skip the sys_id resolution steps. Knit's normalised endpoints return consistent IDs you can use directly:

# Get incidents already filtered and paginated
incidents = requests.get(
    "https://api.getknit.dev/v1.0/ticketing/tickets.list",
    headers={
        "Authorization": f"Bearer {knit_token}",
        "X-Knit-Integration-Id": integration_id
    },
    params={"status": "OPEN", "assignedToId": user_id}
)
# Update an incident's status
requests.post(
    "https://api.getknit.dev/v1.0/ticketing/ticket.update",
    headers={
        "Authorization": f"Bearer {knit_token}",
        "X-Knit-Integration-Id": integration_id
    },
    json={"ticketId": ticket_id, "status": "IN_PROGRESS", "assignedToId": agent_id}
)

Pattern 3: User and Group Sync for Access Control

Many products need to know which ServiceNow users and groups a customer has, to map them to your product's access model:

def sync_users_and_groups(instance: str, token: str) -> dict:
    """
    Sync all active users and groups from ServiceNow.
    Used to populate assignee pickers and map access levels.
    """
    # Fetch users — paginate if the instance has many
    users_response = requests.get(
        f"https://{instance}.service-now.com/api/now/table/sys_user",
        headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
        params={
            "sysparm_query": "active=true",
            "sysparm_fields": "sys_id,name,email,user_name,department",
            "sysparm_limit": 1000,
            "sysparm_exclude_reference_link": "true"
        }
    )
    users = users_response.json()["result"]

    # Fetch groups
    groups = list_groups(instance, token)

    return {
        "users": [
            {"id": u["sys_id"], "name": u["name"],
             "email": u["email"], "username": u["user_name"]}
            for u in users
        ],
        "groups": [
            {"id": g["sys_id"], "name": g["name"]}
            for g in groups
        ]
    }

Building ServiceNow Integrations with Knit

The two hardest parts of a ServiceNow product integration are both auth-related: collecting the instance URL from each customer, constructing per-instance OAuth endpoints, and managing token refresh independently per customer installation. These are real engineering problems that have nothing to do with the value you're delivering to users.

Knit handles ServiceNow authentication — including instance URL collection and per-customer OAuth — so your integration starts from a normalised API call rather than an auth infrastructure build. The same Knit headers work across all your ticketing integrations:

Authorization: Bearer {your-knit-token}
X-Knit-Integration-Id: {customer-integration-id}

This is especially valuable if your product also supports Jira, Zendesk, GitHub Issues, Linear, or Asana — Knit's same API surface covers all of them, so you write the integration logic once.

The Knit APIs available for ServiceNow:

Example: list open high-priority incidents via Knit

/

import requests

def get_open_high_priority_incidents(knit_token: str, integration_id: str) -> list:
    """
    No instance URL handling. No token refresh. No sysparm syntax.
    Works the same way for ServiceNow, Jira, Zendesk, and every other Knit-supported tool.
    """
    all_tickets = []
    cursor = None

    while True:
        params = {"status": "OPEN"}
        if cursor:
            params["cursor"] = cursor

        response = requests.get(
            "https://api.getknit.dev/v1.0/ticketing/tickets.list",
            headers={
                "Authorization": f"Bearer {knit_token}",
                "X-Knit-Integration-Id": integration_id
            },
            params=params
        )
        response.raise_for_status()
        data = response.json()["data"]
        all_tickets.extend(data["tickets"])

        cursor = data["pagination"].get("next")
        if not cursor:
            break

    return all_tickets