Connecting to an outside system usually means providing some kind of credential, like a password, a token, or a certificate. Pasting that credential directly into a configuration makes it hard to know everywhere it's used, and hard to update once it expires or needs to be rotated.

Secrets let you store credentials and other sensitive values once and reference them by name instead of pasting the value into a configuration. A future version of Automations will use Secrets without exposing their values to you while you're configuring the Automation.

Secret Types

When you create a Secret, you give it a name and choose one of five types. Some types also store metadata alongside the secret value: descriptive fields that say how to use the secret but aren't secret themselves. Metadata stays visible after you save the Secret, unlike the value itself.

Basic Secret

Basic holds a username and password, the same combination you would type into a login form. The username is stored as metadata; the password is the secret value.

Token Secret

Token holds a single credential, such as an API key or access token, that a service issues to you instead of a username and password. Many services expect a token to travel with each request. When you create a Token secret, you also record where the token goes, as metadata: either as a header or as a query parameter, meaning it's appended to the web address the request is sent to. You can set one or the other, not both.

Headers Secret

Headers holds one or more custom headers. A header is a small piece of information sent along with a web request, separate from the file or data the request carries. Some services require a specific custom header, with a name they define, to carry your API key or account identifier. Use a Headers secret when a service's instructions tell you to send your credential as a named header rather than as a plain token.

Certificate Secret

Certificate, used for TLS client authentication, holds a certificate and its private key. This is a way of proving your identity to a server using a pair of cryptographic files issued by an organization, rather than a username and password. Use this type when a service requires client certificate authentication for the connection itself.

Key/Value Secret

Key/Value holds an arbitrary set of named values you define yourself. Use this type when a connection needs several pieces of credential information that don't fit Basic, Token, Headers, or Certificate.

Storage and Visibility

Your site always encrypts Secret values for storage. Once you save a Secret, you cannot view its value.

You can edit a Secret's name, description, and metadata without affecting its stored value. You can replace the stored value with a new secret value.

The values of secrets never appear in any logs.

Ownership and Access

Secrets belong to the site or to a Workspace, never to an individual person. A site-owned Secret doesn't belong to any Workspace.

Site Administrators can manage all Secrets, whether they're site-owned or belong to a Workspace.

Workspace Administrators can see and manage only the Secrets that belong to their Workspace. They can't see site-owned Secrets or Secrets belonging to other Workspaces.