Skip to main content

Secrets

A secret is a credential, such as a third-party API key, a bearer token, or a webhook signing key, that Autessa stores for your company and uses on your behalf. Your tools can use a secret when they call an outside service, but no screen, API response, log, or export ever shows its value. A secret is used, never viewed.

What it's for​

  • Calling third-party APIs from tools. A script tool asks for a secret by name and sends it in a header or body. The value is filled in only at the moment the request leaves Autessa, and only for the hosts you allowed.
  • Verifying inbound webhooks. Check an HMAC-SHA256 signature from Stripe, GitHub, Shopify, or your own service against a stored signing key, without the key ever entering your script.
  • Signing request tokens. Some APIs want each request to carry a short-lived JWT signed with a key they issued you. A script tool can sign one with secrets.signJwtHs256 and get back only the token.
  • Sharing access without sharing the credential. Teammates and tools can use a secret without ever seeing it, so nobody can copy a key into another system.
  • Knowing who used what. Every use, change, and reveal is written to the secret's audit log.

From the dashboard sidebar, open Secrets. The page lists every secret you have access to, with its mode, allowed hosts, version, and your access level. Click a secret to see its details, its audit log, and any reveal requests. Click New Secret to create one.

You can also manage secrets from the CLI (autessa secrets ...), the Poweruser API, and the SecretService in a custom app.

Key concepts​

Used, never viewed​

When you create or rotate a secret you type or paste the value once. After that, no read shows it:

  • The builder shows a secret's name, description, mode, allowed hosts, and version. If you turn on Show last 4 and the value is at least 12 characters long, it also shows the last four characters so you can tell keys apart.
  • API and CLI reads return the same details and never the value.
  • When a script uses a secret, it holds an opaque handle, not the value. The value is filled in only inside the outgoing HTTPS request. If the other service echoes the value back, Autessa replaces it with [redacted secret] before your script sees the response.
  • Execution logs, tool responses, agent prompts, and AutessaDB rows only ever contain the handle text.

A value can be up to 16 KB, so it can hold a long token, a PEM-encoded key, or a JSON service-account file.

Names​

A secret's name is how tools and scripts refer to it. Names are unique within your company and use lowercase letters, numbers, _, ., and -. They start with a letter or number and are 2 to 100 characters long, for example stripe-live or acme.api_key. A name can't be changed after the secret is created.

Sealed and Revealable​

Every secret has one of two modes:

ModeCan tools use it?Can a person ever see the value?
SealedYesNo. Not the owner, not an admin, not support.
RevealableYesYes, through a reveal request that someone else approves, shown once.

Choose Sealed for anything you can get again from the provider, which is most API keys. Choose Revealable only when someone may genuinely need to read the value back later, for example a shared account password that has no other copy.

Seal forever​

A Revealable secret can be changed to Sealed at any time with Seal forever. This can't be undone: a Sealed secret can never become Revealable again. Sealing cancels every open reveal request on the secret.

Allowed hosts​

Each secret lists the exact hostnames it may be sent to, such as api.stripe.com. You must list at least one. Hostnames are matched exactly, so api.example.com doesn't also allow example.com or eu.api.example.com, and wildcards aren't accepted.

A secret can have up to 50 allowed hosts. A request that would send the secret anywhere else isn't made. The script gets back an error with the code SECRET_HOST_NOT_ALLOWED. Secrets are only ever sent over HTTPS, and never as part of the hostname itself.

This means that even a tool someone edits by mistake, or on purpose, can't send your Stripe key to any server except Stripe's.

Bound tools​

You can bind a secret to specific tools. Binding changes who can use it:

  • Not bound (the default). Any tool can use the secret, but only when the person or key running the tool has at least Use access to the secret.
  • Bound to one or more tools. Only those tools can use the secret, and they can use it no matter who runs them. This is how a tool can call a paid API on behalf of app visitors, webhook senders, scheduled jobs, or triggers who have no access to the secret themselves.

Runs that don't act for any person, such as background processing started by the platform, can use only secrets bound to the tool they run.

Because binding lets anyone who can run the tool use the secret through it, bind a secret only to tools whose script you trust, and limit who can edit those tools.

Access levels​

Secrets are shared from the standard Share dialog, with three levels of their own:

LevelWhat it lets someone do
UseSee the secret's details and use it from tools they run.
RevealEverything in Use, plus ask to see the value of a Revealable secret. Has no effect on a Sealed secret.
ManageEverything, plus edit the description, allowed hosts, bound tools, and Show last 4; rotate the value; seal; delete; share; read the audit log; and approve or deny reveal requests.

The person who creates a secret owns it and always has Manage. Company admins don't get access to secrets automatically: only the owner and the people, teams, and roles a secret is shared with can see or use it. Ownership can be transferred.

Rotation​

Rotating replaces the value and increases the secret's version by one. Tools keep working without any change, because they refer to the secret by name. The new value is used by every execution that starts after the rotation.

Deleting​

Deleting a secret erases its value immediately. Tools that still refer to it fail with SECRET_USE_DENIED until you point them at another secret.

Audit log​

Every secret keeps an audit log that people with Manage can read. It records who did what and when:

EventWhen it's recorded
CREATE, UPDATE, ROTATE, SEAL, DELETE, SHARESomeone changed the secret or who has access to it.
USEA tool used the secret. Recorded once per execution for each host the secret was sent to, with the tool and the host. Signature checks are recorded with the host hmac.
USE_DENIEDA tool asked for the secret and wasn't allowed to use it.
REVEAL_REQUEST, REVEAL_APPROVE, REVEAL_DENYA reveal request was made, approved, or denied.
REVEAL, REVEAL_DENIEDSomeone viewed the value, or tried to and was refused.

Audit entries describe what happened (the tool, the host, the request, the fields that changed) and never contain the value.

Reveal requests​

Seeing the value of a Revealable secret always takes two people:

  1. Request. Someone with Reveal access asks to see the value and gives a reason (up to 500 characters).
  2. Approve. A different person with Manage access approves or denies the request. Nobody can approve their own request, including the owner. Requests nobody decides on expire after 7 days.
  3. View once. After approval, the requester has 15 minutes to view the value, once, in the builder or with autessa secrets reveal in the CLI, signed in with their own login. Viewing uses up the request. To see the value again, make a new request.

Access is checked again at the moment of viewing: if the requester's Reveal access was removed after approval, the value isn't shown. A Manage holder can also deny a request that was approved but not yet used.

The requester can cancel a request that is still waiting for a decision.

Only a signed-in person can reveal a value. Poweruser keys, app client keys, the identity a script or tool runs under, public app site keys, and scheduled or triggered runs are always refused with MACHINE_IDENTITY_CANNOT_REVEAL, even when they hold an approved request. Automation can use secrets but can never read them.

What automation can't do​

Scripts, tools, agents, apps, scheduled jobs, triggers, and webhook handlers can use a secret through the secrets helper. They can't:

  • read a secret's value, or reveal it, even with an approved request;
  • send it to a host that isn't on the allowed list, or over plain HTTP;
  • put it anywhere other than an outgoing HTTP request. A handle written to an AutessaDB row, an agent prompt, a tool response, or a log is just the handle text.

Showing a person a value from a tool​

Sometimes a tool has to give a person a value that shouldn't be stored, for example a card number fetched from a payment provider's vault using a secret. Turn on Sensitive output for that tool: the person who runs it sees the result, but it's never written to tool history or logs, and only a signed-in person can run it.

Export and import​

When you export a bundle or publish to the Marketplace, secret values never travel:

  • The bundle lists the secrets its tools need, with each one's name, description, mode, allowed hosts, Show last 4 setting, and the tools that use or are bound to it. Values are never included.
  • On import, the wizard asks for a value for each secret, so the receiving company enters its own key.
  • If the company already has a secret with the same name, that secret is used as it is.
  • Otherwise a new secret is created, owned by the person installing, and bound to the newly installed tools where the original was bound.
  • A secret you leave blank is skipped. Tools that need it fail with SECRET_USE_DENIED until you create it.

How to create a secret​

  1. Open Secrets and click New Secret.
  2. Enter a Name, such as acme-api-key, and an optional Description that says what it's for and where it came from.
  3. Paste the Value.
  4. Choose Sealed (recommended) or Revealable.
  5. Under Allowed hosts, add each hostname the secret may be sent to, such as api.acme.com.
  6. Optionally choose Bound tools, and turn on Show last 4.
  7. Click Create. The value is stored and won't be shown again.

From the CLI:

autessa secrets create --name acme-api-key --mode SEALED \
  --value @acme-key.txt --allowedHosts '["api.acme.com"]'

Then use it from a tool. See Use a third-party API key from a tool.

How to rotate a secret​

  1. Get the new value from the provider. If the provider allows two active keys at once, keep the old key active for now.
  2. Open the secret and click Rotate.
  3. Paste the new value and confirm. The version goes up by one, and executions that start from now on use the new value.
  4. Check the audit log for USE events after the rotation, then revoke the old key at the provider.

How to share a secret​

  1. Open the secret and click Share.
  2. Add people, teams, or roles, and pick Use, Reveal, or Manage for each.
  3. Click Save.

Give Use to people who build or run tools that need the secret. Give Manage to at least two people if the secret is Revealable, so one of them can approve the other's reveal requests.

How to see a Revealable secret's value​

  1. Open the secret and click Request reveal.
  2. Enter why you need the value and submit.
  3. Wait for someone with Manage to approve. Their pending requests appear on the secret and in their To approve list.
  4. Within 15 minutes of approval, open the secret and click Reveal. The value is shown once.

How to seal a secret forever​

  1. Open a Revealable secret and click Seal forever.
  2. Confirm. The secret is now Sealed, open reveal requests are cancelled, and nobody can ever see its value again. Tools keep using it as before.