spotlight_secret

The spotlight_secret resource, and the secret resource of the API: a workspace's credential that Spotlight puts in a request header or query parameter on requests to the hosts it is bound to. Its value never enters a sandbox.

See Resource API for the operations, headers and errors every kind shares.

ExampleCopy Anchor Link

resource "spotlight_secret" "acme_api_key" {
  workspace_id = spotlight_workspace.acme.id
  name         = "ACME_API_KEY"
  bindings = [
    { host = "api.acme.example", prefix = "Bearer " },
  ]
  value_wo         = var.secret_acme_api_key
  value_wo_version = 1
}

resource "spotlight_secret" "maps_key" {
  workspace_id = spotlight_workspace.acme.id
  name         = "MAPS_KEY"
  bindings = [
    { host = "maps.googleapis.com", carrier = "query", name = "key" },
  ]
  value_wo         = var.secret_maps_key
  value_wo_version = 1
}

resource "spotlight_secret" "acme_signing" {
  workspace_id = spotlight_workspace.acme.id
  name         = "ACME_SIGNING"
  source = {
    kind      = "aws-secrets-manager"
    secret_id = "acme/signing"
    field     = "secret"
  }
}

FieldsCopy Anchor Link

In Terraform, value_wo is write-only and needs Terraform 1.11 or later.

SourcesCopy Anchor Link

For a run, a secret from AWS Secrets Manager is read by egress with the host's own AWS identity, among the names SPOTLIGHT_EGRESS_READS allows; see Host settings. For an integration request made by Spotlight, it is read only when the deployment reads from AWS Secrets Manager; otherwise the request fails with Secret <NAME> could not be read. This deployment does not read from AWS Secrets Manager.

BindingsCopy Anchor Link

A header may not be host, content-length, content-type, transfer-encoding, connection, upgrade, te or trailer.

In Terraform, the provider refuses a query binding without a name at plan time with A query parameter must be named.

A secret is sent only over HTTPS, and only to a hostname equal to a bound host. A request to any other address goes without it. A value of more than one line cannot be sent: Secret <NAME> holds more than one line. It cannot be sent in a request. A call that would send two secrets in the same header or query parameter to one host is refused with 409 and Secrets <A> and <B> are both worn in <slot> toward the same host. A request can carry only one of them., where <slot> is the header's name or ?<parameter>.

In what a host answers to a tool call, including an error that repeats the URL or the key, every spelling of the value Spotlight sent, and of the value without its prefix, is replaced by [secret]. This happens before the answer is recorded in the task's journal or handed to the agent. An error reaching the host says [secret] in the value's place.

In a query parameterCopy Anchor Link

On a request Spotlight makes, such as an integration tool's call, the parameter's first occurrence is set to the prefix and the value. Later occurrences of the parameter are dropped, and a missing parameter is added at the end. The rest of the query is kept as it was, in its order and its encoding. A redirect to another host never carries the value; the parameter reads [secret] there. In a run's sandbox, egress rewrites the query the same way, and only where the request carries the stand-in as that parameter's value.

Where a secret is namedCopy Anchor Link

A secret is named as secret.<NAME>.

A secret that is named but not defined fails where it is used, with Secret <NAME> not found. Please define it first. A webhook whose signing secret is not defined answers a plain 401. See Delivery address. A skill declares the secrets it needs in the secrets of its SKILL.md, by name only.

No expression may read a secret's value. See Evaluation.

RulesCopy Anchor Link

• Writing a secret needs the manage-secrets permission. See Roles and permissions.
• A secret still named by an integration or a harness profile cannot be deleted. The delete is refused with 409 and Secret <NAME> is in use. Used by: <names>.
• No read, list, import, export or configuration change holds the value. A configuration change records the value version and the bound hosts.
• A secret belongs to the workspace, and every team in it can name it.