temperDocs
QuickstartAPItemper.im
Menu

API reference

Secrets

Developer-defined credentials and egress allowlists: secrets such as model API keys are stored in the control plane and the VM only ever sees placeholder tokens, which the host's credential gateway swaps for the real values per domain. Allowlists are set per developer / per environment and take effect immediately.

Developer-level secrets

GET/v1/secrets

Secrets available to all of this developer's environments, sorted by name. Values are not returned.

Responses

  • 200Secrets SecretList
  • 401Missing, invalid or revoked key
  • 500Internal error (details are recorded only in server logs)

Store (or replace) a developer-level secret

PUT/v1/secrets/{name}

The value is stored encrypted in the credential vault and is never returned by any endpoint. The VM only has a placeholder token (tmpr_…, which the Agent reads from /run/temper/secrets/NAME); when a request goes to one of hosts, the host's credential gateway replaces header with prefix + value; these domains are added to the allowlist automatically. A value change takes effect within 5 minutes and the placeholder stays the same; deletion and domain changes take effect immediately. An environment-level secret with the same name overrides it. Both creating and replacing return 200. Invalid parameters give 400 (see PutSecretRequest).

Request body application/json · PutSecretRequest

FieldTypeDescription
valuerequiredstring

The real value, at most 8192 bytes, with no newlines. Never returned by any endpoint afterwards.

hostsrequiredarray of string

The value is sent only to these exact domains (lowercase, without scheme, port or wildcards).

pathsarray of string

Allowlist of path prefixes (starting with /); omitted or empty = no restriction.

headerstring

The request header that receives the real value, default authorization. Cannot be host, cookie or content-length.

prefixstring

Header value = prefix + real value. Defaults to Bearer when header is authorization, and to empty for custom headers. No newlines.

kindSecretKind

standard: a key the Agent uses on the end user's behalf. Requests that use it go through the action policy as connector secret:NAME (GET/HEAD/OPTIONS count as read, other methods as write). infrastructure: your own infrastructure credential, for example the token your Agent uses to connect back to your backend. It is still sent only to hosts and paths and every use is audited, but requests that use it skip the action policy. A request that also carries a standard or built-in credential is judged by that credential.

Responses

  • 200Stored (value not included) Secret
  • 400Invalid parameters: validation failed, the body is not valid JSON, or the query string could not be parsed (all returned in the same JSON shape).
  • 401Missing, invalid or revoked key
  • 415Missing `Content-Type: application/json` (`unsupported_media_type`)
  • 422The JSON does not match the schema: a missing field, a wrong type or enum value, or an unknown field (`invalid_body`)
  • 500Internal error (details are recorded only in server logs)

Delete a developer-level secret

DELETE/v1/secrets/{name}

Takes effect immediately (the placeholder is invalidated). 404 if there is no such secret.

Responses

  • 204Deleted
  • 401Missing, invalid or revoked key
  • 404Does not exist, or does not belong to this developer (`no such resource`); for a nonexistent route `message` is `no such route`
  • 500Internal error (details are recorded only in server logs)

Environment-level secrets

GET/v1/environments/{id}/secrets

Lists only this environment's own secrets (not developer-level ones). The secrets in effect in the environment are these, plus developer-level secrets not overridden by an environment-level secret of the same name. 404 if the environment does not exist, is not yours, or has been destroyed.

Responses

  • 200Secrets SecretList
  • 401Missing, invalid or revoked key
  • 404Does not exist, or does not belong to this developer (`no such resource`); for a nonexistent route `message` is `no such route`
  • 500Internal error (details are recorded only in server logs)

Store (or replace) an environment-level secret

PUT/v1/environments/{id}/secrets/{name}

Same as setSecret, but only for this environment; it overrides a developer-level secret of the same name (for example, each end user's own key). 404 if the environment is not yours.

Request body application/json · PutSecretRequest

FieldTypeDescription
valuerequiredstring

The real value, at most 8192 bytes, with no newlines. Never returned by any endpoint afterwards.

hostsrequiredarray of string

The value is sent only to these exact domains (lowercase, without scheme, port or wildcards).

pathsarray of string

Allowlist of path prefixes (starting with /); omitted or empty = no restriction.

headerstring

The request header that receives the real value, default authorization. Cannot be host, cookie or content-length.

prefixstring

Header value = prefix + real value. Defaults to Bearer when header is authorization, and to empty for custom headers. No newlines.

kindSecretKind

standard: a key the Agent uses on the end user's behalf. Requests that use it go through the action policy as connector secret:NAME (GET/HEAD/OPTIONS count as read, other methods as write). infrastructure: your own infrastructure credential, for example the token your Agent uses to connect back to your backend. It is still sent only to hosts and paths and every use is audited, but requests that use it skip the action policy. A request that also carries a standard or built-in credential is judged by that credential.

Responses

  • 200Stored (value not included) Secret
  • 400Invalid parameters: validation failed, the body is not valid JSON, or the query string could not be parsed (all returned in the same JSON shape).
  • 401Missing, invalid or revoked key
  • 404Does not exist, or does not belong to this developer (`no such resource`); for a nonexistent route `message` is `no such route`
  • 415Missing `Content-Type: application/json` (`unsupported_media_type`)
  • 422The JSON does not match the schema: a missing field, a wrong type or enum value, or an unknown field (`invalid_body`)
  • 500Internal error (details are recorded only in server logs)

Delete an environment-level secret

DELETE/v1/environments/{id}/secrets/{name}

Takes effect immediately; if a developer-level secret with the same name exists, this environment goes back to using it. 404 if there is no such secret.

Responses

  • 204Deleted
  • 401Missing, invalid or revoked key
  • 404Does not exist, or does not belong to this developer (`no such resource`); for a nonexistent route `message` is `no such route`
  • 500Internal error (details are recorded only in server logs)

Developer-level egress allowlist

GET/v1/egress

Used by every environment that does not have its own allowlist.

Responses

  • 200Allowlist EgressAllow
  • 401Missing, invalid or revoked key
  • 500Internal error (details are recorded only in server logs)

Set the developer-level egress allowlist

PUT/v1/egress

Replaces the whole list (allow: null clears it). Traffic allowed out of the VM is: the platform-level allowlist + this list (or the environment's own) + the domains of this environment's secrets and OAuth connections. Changes take effect immediately, with no VM replacement. At most 200 entries, each an exact domain or *.example.com (lowercase, without scheme or port), otherwise 400.

Request body application/json · PutEgressRequest

FieldTypeDescription
allowrequiredarray of string | null

An exact domain or *.example.com. For an environment, null reverts to the developer-level list; for the developer level, null clears the list.

Responses

  • 200Set EgressAllow
  • 400Invalid parameters: validation failed, the body is not valid JSON, or the query string could not be parsed (all returned in the same JSON shape).
  • 401Missing, invalid or revoked key
  • 415Missing `Content-Type: application/json` (`unsupported_media_type`)
  • 422The JSON does not match the schema: a missing field, a wrong type or enum value, or an unknown field (`invalid_body`)
  • 500Internal error (details are recorded only in server logs)

Egress allowlist of an environment

GET/v1/environments/{id}/egress

The environment's own list if it has one (inherited: false), otherwise the developer-level list (inherited: true). 404 if the environment is not yours or has been destroyed.

Responses

  • 200Allowlist EnvironmentEgress
  • 401Missing, invalid or revoked key
  • 404Does not exist, or does not belong to this developer (`no such resource`); for a nonexistent route `message` is `no such route`
  • 500Internal error (details are recorded only in server logs)

Set an environment's own egress allowlist

PUT/v1/environments/{id}/egress

Replaces the whole list; from then on the developer-level list is no longer used. allow: null reverts to the developer-level list. Takes effect immediately. Domain rules are the same as for setEgress.

Request body application/json · PutEgressRequest

FieldTypeDescription
allowrequiredarray of string | null

An exact domain or *.example.com. For an environment, null reverts to the developer-level list; for the developer level, null clears the list.

Responses

  • 200The allowlist now in use EnvironmentEgress
  • 400Invalid parameters: validation failed, the body is not valid JSON, or the query string could not be parsed (all returned in the same JSON shape).
  • 401Missing, invalid or revoked key
  • 404Does not exist, or does not belong to this developer (`no such resource`); for a nonexistent route `message` is `no such route`
  • 415Missing `Content-Type: application/json` (`unsupported_media_type`)
  • 422The JSON does not match the schema: a missing field, a wrong type or enum value, or an unknown field (`invalid_body`)
  • 500Internal error (details are recorded only in server logs)

Add one domain to an environment's egress allowlist

PUT/v1/environments/{id}/egress/{host}

Adds the domain without touching the others, so concurrent additions never overwrite each other. Adding a domain that is already there succeeds. If the environment was using the developer-level list, that list is copied first and becomes the environment's own. Takes effect immediately.

Responses

  • 200The allowlist now in use EnvironmentEgress
  • 400Invalid parameters: validation failed, the body is not valid JSON, or the query string could not be parsed (all returned in the same JSON shape).
  • 401Missing, invalid or revoked key
  • 404Does not exist, or does not belong to this developer (`no such resource`); for a nonexistent route `message` is `no such route`
  • 500Internal error (details are recorded only in server logs)

Remove one domain from an environment's egress allowlist

DELETE/v1/environments/{id}/egress/{host}

Removes the domain without touching the others. Removing a domain that is not there succeeds. Same copy-on-write rule as adding.

Responses

  • 200The allowlist now in use EnvironmentEgress
  • 400Invalid parameters: validation failed, the body is not valid JSON, or the query string could not be parsed (all returned in the same JSON shape).
  • 401Missing, invalid or revoked key
  • 404Does not exist, or does not belong to this developer (`no such resource`); for a nonexistent route `message` is `no such route`
  • 500Internal error (details are recorded only in server logs)