Connect an integration that signs in with OAuth

Use this page when an integration acts on a service with an OAuth grant instead of a stored key. Whether its tools use the team's grant or the grant of the person who started the task is set by connection.holder; see Holder.

You need:

• An account at the service that may grant the scopes the integration asks for.
• The integration defined for the team with a connection.oauth2 block, as below.
• An OAuth client for the integration. Either Spotlight's deployment holds one, registered at the service with the redirect URL https://app.usespotlight.ai/api/integrations/oauth/callback (on a self-hosted Spotlight, your deployment's address in its place) and looked up by the integration's integration name, or the service registers clients on request and the definition names its registration endpoint. Without either, the connect button opens nothing.
• To connect the team: to be an owner or admin of the workspace. To connect yourself: to be on the team.

Declare the connectionCopy Anchor Link

If the integration does not have one yet, add connection.oauth2 to its definition, and have the requests that act on the service use it. With the Terraform provider:

resource "spotlight_integration" "core_acme" {
  team_id = spotlight_team.core.id
  definition = {
    integration = "acme"
    name        = "Acme"
    connection = {
      oauth2 = {
        authorize = "https://acme.example/oauth/authorize"
        token     = "https://acme.example/oauth/token"
        scopes    = ["issues:write"]
        identity  = "$${{ response.account.name }}"
      }
    }
    actions = {
      comment = {
        request = {
          method = "POST"
          url    = "https://api.acme.example/comments"
          body   = { issue = "$${{ inputs.issue }}", text = "$${{ inputs.body }}" }
          auth   = { oauth2 = { connection = true } }
        }
      }
    }
  }
}

identity is optional. It reads the service's token response and names the account Spotlight shows once connected; point it at whatever field your service returns.

If the integration's tools should act as the person who started each task, set holder = "requester" in connection. A hook cannot call these tools.

For a remote MCP server whose connection discovers its endpoints, a client the deployment holds must also name the issuer of the server's authorization server; see Discovery.

If the deployment holds no OAuth client for the integration, set registration to the service's client registration endpoint. If the service asks which resource the grant is for, set resource to its address:

    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"]
      }
    }

Run terraform apply.

Connect the teamCopy Anchor Link

The service sends you back to the team's Integrations page. Open the row: Team account shows the account the service named, or "Connected" if the integration has no identity. Requests that use auth = { oauth2 = { connection = true } } now carry the team's grant.

A member who is not an owner or admin sees "Waiting for an admin" on the row instead of the button.

Connect yourselfCopy Anchor Link

For an integration with holder = "requester":

The service sends you back to Integrations. Open the row: Your account shows the account the service named, or "Connected". From then on its tools act as you on the tasks you start. To stop that, open the actions menu beside your account and select Disconnect.

An owner or admin also sees People: who has connected, and under "Not connected", the team's members who have not, never their grants. Nobody can disconnect someone else.

Answer a request to connectCopy Anchor Link

If a run on a task you started calls a tool that acts as you, and you have not connected the integration, or the service refused to renew your grant, nothing is sent. The task is assigned to you and your inbox gets an item saying which tool needs your connection. Select Connect in it and authorize at the service. Once you are back, the item is answered with Connected <Name>. and the work resumes.

For what happens when there is nobody to ask, see Holder.

ReconnectCopy Anchor Link

To link a different account, or after the service withdrew Spotlight's access, open the actions menu beside Team account and select Change account, or for your own, select Disconnect and then Connect your account, and authorize again. The new grant replaces the old one.

If it does not connectCopy Anchor Link

If you select Connect team account or Connect your account and the row shows "Could not connect. Try again." instead of taking you anywhere, Spotlight would not begin. Either you may not make that connection (the team's needs an owner or admin; your own needs you to be on the team and the integration to have holder = "requester"), or Spotlight has no OAuth client for the integration: the deployment holds none and the definition has no registration, or the service refused to register one.

If you authorized at the service but land on Spotlight's start page instead of the page you started from, the connection was refused, and Spotlight shows no message. Check that:

• you may make the connection, as above;
• you came back within 10 minutes of starting to connect;
• you did not sign in to Spotlight as someone else in the meantime;
• you approved the request at the service rather than declining it.

Then select Connect again. If it fails every time, the service may be refusing Spotlight's client or its redirect URL, which whoever runs your Spotlight deployment can check.

RelatedCopy Anchor Link

• spotlight_integration: every connection field, and the connect and callback endpoints.
• Give stations a tool from an HTTP API: turn the integration's requests into tools agents can call.
• Roles and permissions: who may make each connection.