Credentials

A captured realm says what it needs to authenticate and never what the secret is. The owner binds a real secret to each declared credential when approving the realm. This is the recommended way for any new realm to ask for a secret.

A conventional realm asks for its keys another way, with keys.yml entries that name the variable a key is stored under. Both declarations work, and each applies to its own kind of realm; keys and declared credentials says which applies where and what happens when both name one secret.

credentials: {
  "statuspage-key": {
    kind: "api-key",
    provider: "statuspage",
    description: "An API key for the status page account the radar reads.",
    docs: "https://developer.statuspage.io",
  },
},

A bearer credential whose provider wants a word other than Bearer in front of the token names it with scheme. A Discord bot token is sent as Bot <token>:

bot: {
  kind: "bearer",
  scheme: "Bot",
  provider: "discord",
  description: "A bot token for the bot the assistant answers as.",
  docs: "https://discord.com/developers/applications",
},

Field	Rule
key	The credential id: [a-z][a-z0-9-]{0,63}. At most 32 credentials.
kind	bearer, api-key, basic, oauth2 or public-key.
description	Required, at most 512 characters. The approval screen shows it to the owner.
provider	Optional, [A-Za-z0-9][A-Za-z0-9_.-]{0,63}.
docs	Optional https:// link, at most 512 characters.
scheme	bearer only: the word sent before the token in Authorization, 1 to 32 printable ASCII characters with no spaces. Defaults to Bearer, which is not written to the file.
scopes	oauth2 only, and required there: 1 to 32 distinct scopes, each at most 128 characters.

value, env, tokenEnv and walletItem are refused, so a captured realm cannot ship or point at a secret, and so is any other field not in the table. A credential nothing references is refused, since it would ask the owner for a secret no call uses. Synth counts a reference from an API entry’s credential (or its deprecated tokenEnv), a channel’s credential, a webhook signature’s credential and the GraphQL source’s credential. credentials.yml lists the credentials sorted by id. Binding, rotation and revocation are described under credentials in the hosted contract. An oauth2 credential is accepted in the declaration, and binding one is refused by the reference host.