Swagger & the OpenAPI spec

Two ways in, both open (no key needed to view them):

• /swagger — interactive UI. Click Authorize, paste your x-api-key, and Try it out runs real requests.
• /openapi.json — the OpenAPI 3 document. Point a client generator at it before you even have a key.

# Generate a typed client from the spec (example)
npx @openapitools/openapi-generator-cli generate \
  -i https://okto-partner-api.oktorocket.io/openapi.json \
  -g typescript-fetch -o ./okto-client

Authentication

Every /v1/* and /mcp request needs your key in the x-api-key header. Authorization: Bearer is not accepted — the gateway rejects it with 403 before the API sees it.

curl "https://okto-partner-api.oktorocket.io/v1/sites" \
  -H "x-api-key: $OKTO_KEY"

A bare {"message":"Forbidden"} is from the gateway (check the header/key). Anything in application/problem+json is from the API (valid key; the issue is scope, parameters or the record). A record outside your scope returns 404, not 403.

Keys are issued by the OktoRocket team against your tenant with only the scopes you ask for. Tell us the shops, the scopes, and whether you want REST, MCP or both — it's one key either way.

Sign in as an OktoRocket user (Cognito)

Where user sign-in has been enabled, you can call the API as yourself with a Cognito access token instead of an API key — the same login you use for OktoRocket. The token surface lives under /oauth (a route that accepts the bearer token and does not require an x-api-key); the plain /v1 and /mcp paths remain key-only. Until sign-in is enabled, use your x-api-key on /v1:

curl "https://okto-partner-api.oktorocket.io/oauth/v1/sites" \
  -H "Authorization: Bearer $COGNITO_ACCESS_TOKEN"

No key is provisioned: the shops and data you can read are resolved automatically from your user account's tenant access, and you get the full read-only scope set. The token must be an access token from the OktoRocket user pool, issued with the openid and email scopes so your verified email can be read. Access tokens are short-lived — refresh them the usual OAuth way.

Admin access only. Signing in with your user account requires the Admin role on the tenant; you then get read access to every shop in that tenant. Any other role — including Manager — is authenticated but returns 403 — no tenant access, because only an Admin sees every shop. There is no per-shop sign-in — if you are site-scoped, or need a machine-to-machine grant, use a tenant/site-scoped API key instead.

MCP clients that support OAuth can sign you in automatically: point the client at /oauth/mcp and it discovers the flow from /.well-known/oauth-protected-resource (a 401 on /oauth/mcp returns a WWW-Authenticate pointer), then opens the OktoRocket login in your browser and attaches the token — no manual paste. Connectors that require Dynamic Client Registration (Claude, ChatGPT/Codex, Grok) are supported too: the server publishes /.well-known/oauth-authorization-server and POST /oauth/register, which creates a callback-bound client id automatically. Add the server URL and sign in; no callback registration or client secret is required from you.

Set up the MCP server on a coding agent

The MCP server speaks streamable HTTP at /mcp with the same key. Where user sign-in is enabled, point the client at /oauth/mcp instead and send an Authorization: Bearer <Cognito access token> in place of the x-api-key header. Point any MCP-capable client at it; the agent discovers the tools and their filters on its own.

Claude, ChatGPT/Codex, and Grok custom connections

In the product's custom connector, app, or MCP settings, add this remote server URL:

https://okto-partner-api.oktorocket.io/oauth/mcp

Choose OAuth or sign in when prompted. The client discovers registration and opens the OktoRocket login automatically. Your OktoRocket user must be an Admin for at least one enabled tenant. This is the recommended customer path while public directory listings are deferred.

If the client supports static request headers instead, use https://okto-partner-api.oktorocket.io/mcp with x-api-key: YOUR_KEY. API keys remain supported and are better for service accounts or site-scoped access; do not put an API key on the OAuth URL.

Claude Code

claude mcp add --transport http oktorocket \
  https://okto-partner-api.oktorocket.io/mcp \
  --header "x-api-key: YOUR_KEY"

Or add it to .mcp.json (project) / ~/.claude.json (user):

{
  "mcpServers": {
    "oktorocket": {
      "type": "http",
      "url": "https://okto-partner-api.oktorocket.io/mcp",
      "headers": { "x-api-key": "YOUR_KEY" }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "oktorocket": {
      "url": "https://okto-partner-api.oktorocket.io/mcp",
      "headers": { "x-api-key": "YOUR_KEY" }
    }
  }
}

Any other streamable-HTTP MCP client

Use the same three facts: transport http (streamable HTTP), URL https://okto-partner-api.oktorocket.io/mcp, header x-api-key: YOUR_KEY. Only POST /mcp is routed; a client that also probes GET /mcp gets a 403 on that probe and should carry on. The transport is stateless — no session to keep alive.

Scopes

One key spans REST and MCP; scopes are per entity family and enforced the same way for a URL or a tool call.

Authenticated REST requests and MCP tool calls are audited in partner_audit_log. Both record the caller and tenant scope; OAuth calls include the user identity and OAuth client id. REST entries include method, route template, status, application request id and duration; MCP entries include tool, arguments summary and record count. REST auditing never records credentials, query strings, request bodies or response data. Gateway access logs also capture request status and latency, including requests rejected before authentication.

Paging & errors

• Lists answer { data, pagination: { cursor, hasMore } }, newest first. pageSize is 1–200 (default 50). Hand the cursor back verbatim — it's opaque.
• siteId is required on every list (reports are per shop) — except /v1/users, where it is an optional filter.
• Dates are plain calendar dates (YYYY-MM-DD), taken as the shop's own day.
• Error slugs live at the end of type in the problem+json body — switch on them: insufficient-scope, invalid-request, invalid-cursor, missing-parameter, not-found.

Notes for coding agents

• The authoritative, machine-readable contract is /openapi.json — prefer it over scraping this page for endpoint shapes.
• Over MCP, call list_sites first to learn which siteIds the key reaches, then pass one to every other tool.
• REST and MCP are at parity: each MCP list_*/get_* tool maps to a /v1/* route with the same filters and the same response fields.

Changelog

Newest first. See /openapi.json for exact request/response shapes.

Latest

• User sign-in is Admin-only. Signing in with your OktoRocket user account requires the Admin role on the tenant and grants read access to every shop in it; any other role (Manager included) is authenticated but gets 403, since only an Admin sees all shops. Use a tenant/site-scoped API key for site-scoped users or a machine-to-machine grant.
• MCP OAuth sign-in. OAuth-capable MCP clients can connect to /oauth/mcp and sign in via the browser — the server advertises /.well-known/oauth-protected-resource and challenges with WWW-Authenticate, so the client discovers the OktoRocket login (no pasted token).
• Self-registering connectors (Claude, ChatGPT/Codex, Grok). Connectors that need Dynamic Client Registration now work: the server publishes /.well-known/oauth-authorization-server and POST /oauth/register, which creates a callback-bound public client automatically — add the MCP URL, sign in, done.
• Repair-order & inspection notes. GET /v1/repair-orders/{id} now returns a per-job note and an inspection array of DVI finding notes (item / category / note / severity). Plain text — no author or timestamp. The per-job note fills in as the relay backfills Tekmetric job notes.
• Payments (PMS cash reporting). New GET /v1/payments (MCP list_payments), cursor-paginated per site (siteId required), newest-paid first, with from/to on the cashiered date. One row per paid repair order: amountPaid (total − balance), total, balanceDue, paidAt, and a methods breakdown when the PMS relays one. Money only, no card/processor data; sourced from the relayed repair order (SMS-agnostic). from/to are shop-local calendar dates (the shop's timezone): from from the start of that local day, to through the end of it — so daily totals work directly and the last day isn't clipped. Needs read:payments.
• Repair-order workflow, vehicle & technician. GET /v1/repair-orders/{id} (MCP get_repair_order) now returns a workflow timeline (each stage transition with status/start/end, oldest-first — the authorization history and per-stage timing), the milestones estimateSentAt, inspectionSentAt, promisedAt (due-out) and customerViewedAt, a decoded vehicle object (year/make/model/submodel/vin/plate/engine), and a per-job technician.
• Repair-order jobs & costs. GET /v1/repair-orders/{id} (MCP get_repair_order) now returns a jobs array — per job: name, state (approved / pending / declined), labor & parts sales, labor & parts cost, hours, and authorized/completed timestamps — plus RO-level laborCost/partsCost/subletCost and grossProfit. Costs are summed from the approved line items and reconcile with the RO-summary report; they are null on a repair order with no line items.
• Sign in as an OktoRocket user. Where enabled, call the API with a Cognito Authorization: Bearer access token instead of an API key — your shops and scopes come from your user account. See Authentication.
• Call AI summary & transcript. GET /v1/calls/{id} now returns the AI summary, tags, scorecard score and a hasTranscript flag; a new GET /v1/calls/{id}/transcript returns the transcript (format=text|utterances|both, includeWords, speakerLabels). MCP: get_call, get_transcript.
• Users & employee maps. New GET /v1/users, /v1/users/{id} and /v1/sites/{siteId}/employee-map (MCP: list_users, get_user, get_site_employee_map) under a new read:users scope — resolve a repair order's or call's advisor id to a person. Join a call's answeringExtension to a user's extension.
• Answering extension on calls. /v1/calls and the list_calls tool now return answeringExtension (the VOIP extension that handled the call) and accept an extension filter, so you can pull the calls a given station handled.
• Repair-order totals corrected. totals.total no longer counts a shop-supplies fee twice; it now equals the dashboard's sales total. Affected shops whose point-of-sale reports supplies as a separate fee.
• Analytics on REST. get_ro_summary, goal_vs_actual, get_sales_per_day and get_rollover are now also /v1/analytics/* REST endpoints, at parity with the MCP tools. Advisor- and tech-level gross profit and cost are available via breakdown=advisor (or tech).
• Fixed: the analytics tools (get_ro_summary, goal_vs_actual, get_sales_per_day) intermittently returning "An error occurred invoking …". They now return reliably.
• Fixed: the repair-order detail response no longer advertises cost fields it did not return.

Earlier

• Campaigns, sends and runs, plus the full marketing-attribution suite, on REST and MCP.
• Sales-per-day and rollover analytics; RO-summary and goal-pacing analytics.
• Multi-tenant API keys and key management.
• OpenAPI spec published at /openapi.json for client generation.
• Core resources: sites, repair orders, appointments, calls, goals, contacts, vehicles, messages.
• Ongoing performance and reliability improvements.