spotlight_integration

The spotlight_integration resource, and the integration resource of the API: a team's definition of an outside service, with the webhooks it sends, the happenings they raise, the tools agents may call on it, and how Spotlight connects to it. Its body is a definition object, sent as the definition of spotlight_integration in Terraform or as the JSON body of the resource API.

See Resource API for the operations, headers and errors every kind shares, and Expressions for how the expressions inside a definition are written and what each sees.

ExampleCopy Anchor Link

resource "spotlight_integration" "core_acme" {
  team_id = spotlight_team.core.id
  definition = {
    integration = "acme"
    name        = "Acme"
    webhook = {
      verify = {
        hmac = { secret = "secret.ACME_SIGNING", header = "acme-signature" }
      }
      events = [{
        when = "$${{ body.type == \"issue\" && body.action == \"updated\" }}"
        raise = {
          happening = "acme.issue.updated"
          marks     = [{ kind = "acme.issue", value = "$${{ body.issue.id }}" }]
        }
      }]
    }
    actions = {
      comment = {
        request = {
          method = "POST"
          url    = "https://api.acme.example/comments"
          body   = { issue = "$${{ inputs.issue }}", text = "$${{ inputs.body }}" }
          auth   = { secrets = ["secret.ACME_API_KEY"] }
        }
      }
    }
    tools = {
      comment = {
        does        = "comment"
        description = "Comment on an Acme issue."
        inputs = {
          issue = { type = "string", required = true }
          body  = { type = "string", required = true }
        }
      }
    }
  }
}

Acme stands for any HTTP service. A station gives this tool as acme.comment.

Top levelCopy Anchor Link

A definition must do something: it has a webhook, a poll, a schedule, at least one action, at least one on binding, an openapi, a graphql or an mcp. Otherwise it is refused with must do something: a webhook, a poll, a schedule, an action to run, or an API description or MCP server to offer tools from. A definition with two of openapi, graphql and mcp is refused with offers tools from one source: an openapi, a graphql or an mcp, not two.

A read adds three fields that cannot be set:

In Terraform, tools is known only after apply when the definition has an openapi, a graphql or an mcp. A station that names a generated tool through it that is not there fails the apply, not the plan.

NamesCopy Anchor Link

A happening that does not begin with the integration's name is refused. One integration may not raise the same happening twice, offer the same tool twice, or bind the same task event twice.

An integration named github receives no webhook deliveries at its team address: every delivery there returns 401. The name github belongs to the built-in GitHub source.

ShapesCopy Anchor Link

A shape is a map from field name to a type, written as text such as string, list<Issue> or a type name from types, or to a nested shape. Shapes appear in types, webhook.shape, poll.shape and a request's response. They are used only to type-check expressions. A shape that cannot be read, or types that name themselves in a cycle, produce a warning and are then ignored.

ConnectionCopy Anchor Link

Without discover, oauth2 must name both authorize and token. With discover = true it takes only scopes, identity and resource; naming authorize, token or registration beside it is refused as an unrecognized key. discover without an mcp block is refused at connection.oauth2 with discovers how to connect from its MCP server, but mcp.url names no MCP server.

holder = "requester" without oauth2 is refused with Integration <integration> takes each person's connection. A person can connect only over oauth2.

connection = {
  holder = "requester"
  oauth2 = {
    authorize    = "https://acme.example/oauth/authorize"
    token        = "https://acme.example/oauth/token"
    registration = "https://acme.example/oauth/register"
    resource     = "https://api.acme.example"
    scopes       = ["issues:write"]
  }
}

HolderCopy Anchor Link

A team connection is made by an owner or admin of the workspace. A person's connection is made by that person, who must be on the team, and only for an integration whose holder is requester. See Integration connections.

When a tool of a requester integration is called, nothing is sent until Spotlight has that person's connection. It never uses the team's connection in its place.

<integration> is the integration's name. A hook step that calls a tool of a requester integration fails with not-allowed.

OAuth connect and callbackCopy Anchor Link

An integration with connection.oauth2 shows a Connect team account button, and Change account once linked, on the team's Integrations settings page. An integration whose holder is requester also shows Connect your account there, where each person connects their own account. It links only when Spotlight has an OAuth client for it: one the deployment holds for the integration's name in OAUTH_CLIENTS, or one registered at oauth2.registration.

The state expires after 10 minutes. A request with auth.oauth2 sends the access token as Authorization: Bearer.

RenewalCopy Anchor Link

One renewal of a connection runs at a time, across every control-plane instance, under a claim held for 30 seconds. A request answered 401 while another renewal holds the claim waits for it, for up to 30 seconds, and is sent again with the new token. A refresh token the host rotates is kept. When the host refuses to renew, the connection is marked refused until it is made again. A person whose connection is refused is asked to connect again the next time a tool needs it.

Client registrationCopy Anchor Link

When the deployment holds no OAuth client for the integration and oauth2.registration is set, Spotlight registers a client at that endpoint the first time someone in the team connects, once per team and integration. The registration is a POST of JSON with client_name Spotlight, the callback URL as the one redirect_uris entry, grant_types authorization_code and refresh_token, response_types code and token_endpoint_auth_method client_secret_post. The answer must hold a client_id; a client_secret is kept sealed, with its client_secret_expires_at. The client is reused until the registration endpoint or the callback URL changes or the client secret expires, and is then registered again. A client without a secret sends no client_secret on token requests.

The registration endpoint must be on the deployment's outbound allow-list, as the token endpoint must.

DiscoveryCopy Anchor Link

With oauth2.discover, Spotlight finds where to connect from the MCP server named in mcp.url, following the MCP authorization specification, when a connection begins, when its code is exchanged and when it is renewed:

1. It sends the server an initialize request without credentials. A 401 whose WWW-Authenticate names resource_metadata points at the server's protected resource metadata (RFC 9728). Otherwise Spotlight reads /.well-known/oauth-protected-resource with the server's path after it, and then at the root.
2. It reads the authorization server metadata (RFC 8414, then OpenID Connect discovery) of the first of the metadata's authorization_servers, or of the server's own origin when there is none.

Discovery fails when the authorization server metadata's issuer is not the URL it was read for (RFC 8414), when its code_challenge_methods_supported does not list S256, or when the protected resource metadata names a resource that is neither mcp.url nor on its origin above its path. Then the integration does not link, and beginning a connection answers 404. Every request goes only to hosts on the deployment's outbound allow-list, and each waits at most 15 seconds. What was found is kept for 10 minutes on each control plane server.

The client a connection uses is bound to the authorization server it was made with: its issuer, authorization endpoint and token endpoint.

WebhookCopy Anchor Link

Delivery addressCopy Anchor Link

On a self-hosted Spotlight, use your deployment's address in place of app.usespotlight.ai.

POST https://app.usespotlight.ai/api/webhooks/w/<workspace slug>/t/<team key>/<integration>

An accepted delivery whose processing fails is retried up to 8 attempts in all, from 2 seconds apart doubling to 1 hour.

VerifyCopy Anchor Link

hmac:

token:

asymmetric:

jwt:

A jwt token must be signed with RS256. An expired token is refused.

verify accepts no other way. oauth2 and secrets are refused with verifies a delivery by hmac, token, asymmetric or jwt.

EventsCopy Anchor Link

webhook.events and poll.events are lists of events. Each event is read against every delivery or poll response, in order, and raises one happening when its when holds.

RaiseCopy Anchor Link

A raise must name a branch or at least one mark with find: true; otherwise it is refused with needs a branch or a mark. Without one, no task can be found from it. When neither evaluates to a value, reading the delivery fails.

Mark:

opens:

A task opens only on a line of the team whose role is onto, and only when the raise carries at least one mark.

attaches:

PollCopy Anchor Link

A poll whose request is refused raises nothing.

ScheduleCopy Anchor Link

ActionsCopy Anchor Link

Each entry of actions is { "request": <request> }. Action names are lowercase words joined by dashes, at most 64 characters.

RequestsCopy Anchor Link

A request appears in actions, poll.request, lookup.request and attaches.fetch.

Without expect, a request succeeds on any 2xx status. An expression in url, query, headers or body that fails to evaluate fails the request before it is sent.

auth:

auth accepts no other way, and is refused with authenticates a request by its oauth2 connection, or by the secrets it wears toward the hosts they are bound to. See Bindings.

Every request goes only to hosts on the deployment's outbound allow-list, OUTBOUND_ALLOWED_HOSTS. A request to another host is refused with Outbound call to <host> refused. Host is not on the allowed list. A request is also refused with Outbound call to <url> refused. URL is not valid., Outbound call to <host> refused. redirected more than 5 times, or Outbound call to <host> refused. is where an https request was redirected to over plain http, which Spotlight does not follow.

ToolsCopy Anchor Link

Input:

An input may not be named json: Spotlight keeps that name for handing a tool every input at once, and refuses the tool with tool <integration>.<tool> cannot take reserved input json. That input hands a tool every input at once.

An agent calls a tool as <integration>.<tool>. A tool with approval also takes intent from the agent, which is shown to the person and never sent; see What the agent wants. A tool whose request fails returns the integration answered <status>: <body>, with the body cut at 500 characters. See Approvals and Require approval before a tool runs.

For an integration with connection.oauth2, the answer to a tool call carries actingAs beside output: whose connection the call used, as holder (team or person), personId (for a person) and handle, the account the host named. spotlight <tool> prints only the output. See Holder.

A tool that a station gives or a hook matches or calls cannot be withdrawn from the definition; the update is refused with 409.

Input schemasCopy Anchor Link

Before a call reaches the host, Spotlight checks each input against its schema. These keywords are kept: type (one or a list of string, number, integer, boolean, object, array, null), enum, const, properties, required, additionalProperties (as a boolean), items, anyOf, oneOf, allOf (merged into one object), description, default, examples, minimum, maximum, minLength, maxLength, pattern and format. Others are dropped. pattern and format are kept for the agent to read and not checked. A schema is read 8 levels deep.

A value given as text, as a command-line flag gives it, is read as the input's type first: a number from its decimal digits (not 0x10), true or false, and a list or object from its JSON. A call whose input does not fit is refused before anything is sent, naming where:

<why> is one of is not <type>, is not one of <values>, is not <value>, needs <field>, takes no <field>, is shorter than <n> characters, is longer than <n> characters, does not match <pattern>, is less than <n>, is more than <n>, is none of the shapes it may take, and is not JSON for a value that is not JSON or nests more than 64 levels.

A person who changes a call's inputs while approving it is checked against the same schemas. See Changed inputs.

API descriptionsCopy Anchor Link

openapi and graphql name an API description: a document that lists an API's operations and what each takes. Spotlight reads it and offers one tool for each operation, beside the tools in tools. A definition has at most one of the two. See Generate tools from an API description.

openapi = {
  url      = "https://petstore3.swagger.io/api/v3/openapi.json"
  baseUrl  = "https://petstore3.swagger.io/api/v3"
  revision = "1"
  auth     = { secrets = ["secret.PETSTORE_KEY"] }
  tools = {
    include  = ["*pet*"]
    exclude  = ["delete-*"]
    approval = { "update-pet" = false }
  }
}

openapiCopy Anchor Link

Spotlight reads OpenAPI 3.0 and 3.1. An openapi with both or neither of url and document is refused with is read from a url, or written out in full as its document, but not both.

graphqlCopy Anchor Link

A generated call selects, at each level, every field that takes no required argument: scalar and enum fields at every level, and fields with fields of their own while depth allows. Input objects in arguments are followed 3 levels deep; deeper ones read as any object.

Choosing toolsCopy Anchor Link

A pattern is a tool name in lowercase letters, digits and -, where * matches any run of characters. Anything else is refused with is a tool name in lowercase words joined by dashes, with * for any run of letters, as in *-issue*.

A tool in tools with the same name as a generated one is offered in its place. A key of approval that names no generated tool gives a warning: names <key>, but no operation of its <OpenAPI description, GraphQL schema or MCP server> has that name.

At most 1,000 tools are generated, counted after include, exclude and the tools in tools. More is refused at <openapi, graphql or mcp>.tools with offers <n> tools from its <OpenAPI description, GraphQL schema or MCP server>. A station can choose between at most 1000 tools. Please name the tools to offer in <openapi, graphql or mcp>.tools.include.

Generated toolsCopy Anchor Link

Each OpenAPI operation, and each GraphQL query and mutation field, becomes a tool:

OpenAPI schemas are followed 8 levels deep, and each operation's input schemas are cut short after 4,000 schema nodes; deeper parts read as any value. Only $refs inside the description are followed; any other reads as any value. Spotlight sends the accept, content-type and authorization headers itself, so header parameters by those names are not inputs. An optional parameter or body a tool cannot send is left out.

Every request, written or generated, follows at most 5 redirects. Each goes only to a host on the deployment's outbound allow-list and never from https to http, and credentials are not sent to a host other than the request's own.

An operation that gets no tool gives a warning at openapi or graphql, as passes over <operation>. <reason>:

Reading the descriptionCopy Anchor Link

Spotlight reads the description when the integration is created, and keeps what it read. It reads it again only:

• when an update changes url, document, baseUrl, revision, depth, or whether auth is oauth2 or secrets;
• on any update after a read that failed;
• when the team's connection to the integration is made over OAuth.

A tool call never reads it.

The description is fetched with GET, and a GraphQL schema with an introspection POST. Spotlight sends auth with the fetch only to the API's own host: the host of baseUrl for openapi, and of url for graphql. Without baseUrl, an OpenAPI description is fetched without auth. With auth.oauth2, the fetch carries the team's connection, even for a requester integration. The fetch and every redirect go only to hosts on the deployment's outbound allow-list. See Limits and timeouts for the size and time Spotlight allows.

A description that cannot be read does not refuse the definition. described.problem says why, and the same reason is a warning at <openapi or graphql>.url, or at .document when that is given. The tools of the last read that succeeded stay offered; before any such read, none are. Problems include:

DescribedCopy Anchor Link

An export writes the openapi, graphql or mcp block as part of the definition, and each secret its auth names as a reference to that spotlight_secret.

MCP serversCopy Anchor Link

mcp names a remote MCP server. Spotlight lists the server's tools and offers one tool for each, beside the tools in tools, and makes every call itself. See Call a remote MCP server.

connection = {
  oauth2 = { discover = true }
}
mcp = {
  url  = "https://mcp.acme.example/mcp"
  auth = { oauth2 = { connection = true } }
  tools = {
    exclude  = ["delete-*"]
    approval = { "create-comment" = false }
  }
}

mcpCopy Anchor Link

Server toolsCopy Anchor Link

A tool the server lists that gets no tool gives a warning at mcp, as for an API description: passes over <tool>. <reason>, where the reason is It has no name that a tool can take, It takes <name>, which a tool cannot take, Another operation is also called <name>, or a reason its input schema cannot be read for. The server's resources and prompts are not offered.

Listing the toolsCopy Anchor Link

Spotlight lists the tools when the integration is created, and again:

• when an update changes url, or whether auth is oauth2;
• on any update after a listing that failed;
• when the team's connection to the integration is made over OAuth;
• when the last listing is older than the deployment's MCP_RELIST_SECONDS, 600 by default, checked every minute. One control plane server claims each such listing, moving described.readAt on as it does, and the integration's version does not change.

The listing carries the team's connection when auth is oauth2, even for a requester integration. A listing answered 401 renews the connection once and lists again with the new token, as in Renewal. A listing that fails keeps the tools of the last one that succeeded, as for a description; see Reading the description. A listing that succeeds without a tool the integration offered stops offering it, and the workspace's configuration changes record the change, with each tool no longer offered in details.stranded.

Problems a failed listing gives in described.problem include:

Calling a toolCopy Anchor Link

Spotlight keeps MCP sessions for each server, team, integration, kind of auth, connection holder and access token, and never shares one between holders. A session carries one call at a time; calls made at once each get a session of their own. A session unused for 5 minutes is ended at the server and closed. When the server answers 404 because it has forgotten the session, Spotlight starts a new one and calls once more. Spotlight opens no stream for the server to send on outside a call: the GET stream of the streamable HTTP transport is not opened. A call answered 401 with auth.oauth2 is renewed and retried once, as in Renewal.

Spotlight declares no client capabilities and answers no request from the server other than ping. A server that asks a question in the middle of a call (MCP elicitation) is refused, and the call fails with using <tool>: the MCP server asked a question in the middle of the call. Spotlight refused the call. It does not pass such questions on to a person. A result marked isError fails the call with using <tool>: the MCP server answered with an error: <text>, cut at 500 characters. An answer over 4 MB fails the call with it is larger than the 4 MB Spotlight reads from a tool.

OnCopy Anchor Link

on maps a task event to a binding. The events are:

Binding:

A binding runs only when target holds a channel or a thread. Otherwise nothing is sent.

Secrets in expressionsCopy Anchor Link

No expression may read a secret. An expression containing secret. or secret[ is refused with reads a secret's value. No expression may read a secret. Please name the secret in auth.secrets, and Spotlight wears it toward the hosts it is bound to.

Secret references are not checked against the workspace's secrets when the definition is written. A request that uses a missing secret fails with Secret <NAME> not found. Please define it first.

Errors and warningsCopy Anchor Link

A definition that does not match the schema, an expression that does not parse, and a broken rule above are errors: the write is refused with 422 and each problem is listed at its path, as in webhook.events[0].raise.happening. An expression that parses but does not type-check is a warning: the definition is kept, and the warning is returned in warnings. See Type-checking.