Agents

Workspace secrets

Store an API key once, reference it from a tool header, and understand why it is never shown again and what blocks a delete.

A secret is one named value that belongs to the workspace, sealed on the way in and referenced by name from a tool. Create it once and pick it from a list afterwards, so an API key lives in one place instead of being pasted into every tool that needs it. A secret only ever becomes an HTTP header on an outbound call. For a username and password, a bearer token or OAuth2, use an auth connection instead.

What you need

  • Membership of the workspace. The secret controls ask for membership and no further permission, so every member can create and delete one.
  • The value itself, in a form you can paste. You will not be able to read it back afterwards.

Steps

Step 1: Open the settings page

Go to Settings in the agents navigation. The page opens on the secrets tab, under the line "Reusable secret values referenced by your tools."

Step 2: Press New secret

New secret opens a two-field dialog titled New secret. The same button is offered inside the empty state when the workspace has none yet.

Step 3: Name it

Name is required and is the only thing you will see in the list afterwards, so it has to carry the meaning on its own. The field is monospaced and the placeholder is STRIPE_KEY. Leading and trailing spaces are trimmed, and the name must be unique inside the workspace.

Step 4: Paste the value

Value is required and never echoed back. The box grows with the content, so a long key or a multi-line value fits.

Step 5: Save

Save creates the secret and returns you to the list.

Get it right

You never see the value again, and you cannot edit it, so the name is the only handle you have. Name the system, the environment and the kind of credential.

Recommended

STRIPE_LIVE_SECRET_KEY
ORDERS_API_KEY_PROD

Less effective

key
new_key_2

What happens next

The value is sealed before it is stored. It is encrypted with AES-256-GCM under a key issued by AWS KMS for that one secret and bound to your workspace, so one secret's value cannot be opened in the context of another.

Afterwards you get back the id, the name, the timestamps and a masked hint shaped like ••••AB12: four bullets and the value's last four characters. The value itself is never returned.

The new secret appears in the list with a lock glyph, its name, and a usage chip beneath it reading Not used, Used in 1 tool, or the same line with the count for more than one. Opening that chip lists the tools by name under Used by.

Where a secret can be used

A secret is always a header. Two places accept one.

Place How it is picked Rule
A webhook tool's parameter Set the parameter's Value to Secret, then choose the secret Header parameters only
An imported OpenAPI operation's fixed field Pin a header parameter to a secret in the operation's contract pane Header parameters only

Both refuse anything else at save. A webhook parameter in the path, query or body group is rejected with Secret parameter "<name>" is only allowed in headers, and an OpenAPI field with Secret values are only allowed on header parameters (operation "<name>", field "<name>").

The secret a tool references must still exist when the tool is saved. A missing one is refused with Referenced secret not found for a webhook tool and Referenced secret not found for operation "<name>" for an OpenAPI import.

When the call is made the value is read, placed into the named header and sent. It is not kept on the tool, not written into the request EchoNova shows you, and never given to the agent. An opened value is held in memory for at most five minutes and is not written anywhere.

Create new in a tool's secret picker brings you to this settings page rather than opening a dialog in place. The picker itself lists the workspace's secrets by name, with No secret at the top.

Rotating a value

There is no edit. A secret is created once and then referenced or deleted, so a new value means a new secret:

  1. Create a second secret with the new value under a new name.
  2. Repoint every tool that used the old one.
  3. Delete the old secret.

Do it in that order. Deleting first breaks the tools that still point at the old secret, and step 2 is what releases the delete in step 3.

Deleting one

Delete on the row menu asks to confirm, naming the secret and warning that "Tools that reference it will break."

Before the secret is removed, EchoNova checks whether any webhook tool in this workspace still points at it. If one does, the delete is refused with a 409 and the message Secret is in use by a tool, which the portal shows as "In use by a tool. Remove the reference first."

Limits

Limit Value Applies to
Name Required, trimmed, unique in the workspace Create
Value Required, non-empty Create
Editing Not offered. Create a new secret and repoint The whole lifetime of a secret
Reading the value back Not returned anywhere The whole lifetime of a secret
Where a reference may sit HTTP headers only Webhook parameters and OpenAPI fixed fields
Permission Workspace membership, nothing further Every secret control
Opened value held in memory 5 minutes Tool calls

Troubleshooting

"Duplicate value for name"

Another secret in this workspace already uses that name. Names are unique per workspace and the check is exact. Pick a different one.

"In use by a tool. Remove the reference first."

A webhook tool still has a header parameter pointing at this secret. Open the usage chip on the row to see which tools, clear the reference in each, then delete again.

Your endpoint answers 401 after a change to secrets

The header is missing, not wrong. A secret that cannot be read when the call is made is left out rather than failing the call, so the request goes out without it. Check that the secret still exists and that the tool still names it.

The secret I just created is not in the tool's picker

The picker loads the list once when it is drawn. Reopen the tool form so it fetches the list again.

FAQ

Can I see a secret again after creating it?

No. The value is not returned anywhere and the portal has no reveal control. You get a masked hint of the last four characters and nothing else.

Can the agent read a secret?

No. Secret parameters are filled in after the agent has produced its arguments, and the value is written straight into the outgoing header.

Can I use a secret in a URL, a query string or a body?

No. Both the webhook builder and the OpenAPI operation editor restrict secrets to header parameters and refuse anything else at save.

Is a secret shared between agents?

Yes. Secrets belong to the workspace, not to an agent. Any tool in the workspace can reference one, and every agent that uses that tool gets the same value.

What is the difference between a secret and an auth connection?

A secret is one opaque value that becomes a header you name. An auth connection is a whole credential with a method attached, and it always produces the Authorization header itself. Use a secret for an API key header, and an auth connection for basic, bearer or OAuth2.

Does deleting a tool delete the secrets it used?

No. The secret stays in the workspace, and the usage chip drops to Not used once nothing references it.