Personas

The Personas service gives your agents the identities they work as on outside systems: a mailbox, an API account, an app registration. Each Persona records who that identity is and holds its one credential, whose secret is kept in the platform's keychain rather than in a conversation. An agent passes a Persona's id to another service, and that service signs in with it.

A Persona belongs to your account, and every agent of the account shares it.

It offers a trial, and it can also be enabled in full and billed per use.

Every tool works on this system's own storage only; none reaches outside it. No tool signs in to the outside system or checks that a credential works.

Its tools

Each tool is charged under an operation of its own, named in brackets at the end of its entry: one unit per call.

Every tool that answers a Persona answers it without its secret, with its dates in ISO form, and with a notice for each Persona in the answer whose secret has expired or expires soon (see Expiry and notices). A Persona is named by its personaId, the id personas_list answers.

Tools that only read

personas_list lists your account's Personas: every one, or with tag only those carrying that tag, or with expiresWithinDays only those whose secret expires within that many days, the already expired included. Give both to have both apply. It only reads (personas-list).
personas_get returns one Persona: its name, purpose, identifier, system kind, credential type and that credential's non-secret details, whether it is revealable, when its secret expires, its tags, and when its secret was last replaced and the Persona created and last changed. It only reads (personas-get).

Tools that change things and lose nothing

personas_create makes a new Persona from a name, an optional purpose, its externalIdentifier on the outside system (an address, a user name, an app id), its systemKind, its credential, the credential's secret, an optional secretExpiresAt, revealable and optional tags. A name your account already uses, compared without regard to letter case, is refused. revealable is chosen here, once: false can never be changed to true (personas-create).
personas_add_tag puts one tag on a Persona. A tag it already carries leaves it as it was (personas-add-tag).
personas_remove_tag takes one tag off a Persona. A tag it does not carry leaves it as it was (personas-remove-tag).

Tools that replace, disclose or remove, with no undo

personas_update changes any of a Persona's name, purpose, externalIdentifier, systemKind and credential, leaving the rest as they are; at least one must be given. A purpose of null clears it. The credential's type cannot change, and a credential given replaces the whole of its non-secret details: a client-secret credential sent without tenantId clears it. What it overwrites keeps no history and cannot be recovered. The secret is untouched (personas-update).
personas_replace_secret gives a Persona's credential a new secret, and a new secretExpiresAt or, when that is left out or null, no expiry. The previous secret is overwritten and cannot be recovered; the credential's non-secret details are untouched (personas-rotate).
personas_lock makes a revealable Persona unrevealable, for good: this cannot be undone. Locking one already locked leaves it as it was (personas-lock).
personas_reveal returns the secret of a revealable Persona, in its answer and nowhere else. A Persona created unrevealable, or locked since, is refused, and nothing is revealed. Each reveal is recorded (see Revealing and locking). Its answer comes back whole and is never stored or paged. A secret once in a transcript cannot be taken back out of it (personas-reveal).
personas_delete deletes a Persona and erases its secret. Nothing of it can be recovered (personas-delete).

Credentials

A Persona holds one credential, of one of three types. The secret is given apart from the credential, as secret, and is never part of an answer except personas_reveal's.

password: a username, and the password as the secret.
api-key: nothing besides the key, which is the secret.
client-secret: a clientId and, optionally, a tenantId, and the client secret as the secret.

systemKind says which kind of system the Persona belongs to: microsoft-365, google-workspace, imap, smtp, http-api or other.

Microsoft and Google refuse plain password sign-in for accounts with multi-factor authentication on their modern APIs. A password Persona is therefore for IMAP, SMTP and other services that accept one, not for a Microsoft or Google mailbox reached through those companies' APIs; use a client-secret Persona for an app registration there.

Expiry and notices

A secret may carry an expiry, secretExpiresAt: a date and time with its zone, written YYYY-MM-DDThh:mm:ssZ or with an offset in place of the Z. It is stored and shown with the Persona, and a Persona whose secret has expired is marked secretExpired (EXPIRED in the text). An expired secret is reported, never blocked: the Persona still works for as long as the outside system accepts the secret. Replace it with personas_replace_secret, which also sets the new expiry.

Every answer that carries a Persona also carries a notice for each Persona in it whose secret has expired or expires within your account's warning window: as a line beginning Notice: after the answer's text, and in the answer's notices list, each naming the Persona, its expiry and the whole days left (negative once expired). A Persona with no expiry, or one further off than the window, carries none. The window is a setting (see Its settings).

Revealing and locking

Whether a Persona's secret may ever be shown is chosen when it is created, with revealable. A Persona created unrevealable stays so: its secret can be set, replaced and used by reference, and no tool returns it.

personas_reveal returns the secret of a revealable Persona only. personas_lock turns revealable off, and nothing turns it back on, so a Persona once locked is refused by personas_reveal from then on.

Every reveal is recorded: who revealed it, when, and on which surface (through the tools or on the dashboard), never the value. A reveal that cannot be recorded returns nothing. The record of a reveal is kept when the Persona is later deleted.

Its settings

services.personas.max-personas is the most Personas your account may hold, which you can set to at most 100 Personas. The platform has a ceiling of its own on it, and the smaller of the two is the cap in force. Lowering it deletes nothing: Personas already held stay, and only the next create past the cap is refused.

services.personas.expiry-warning-days is how many days before a secret's expiry its Persona starts carrying a notice, from 0 to 365 days. At its lowest, only secrets already expired carry one.

Its limits

A Persona's fields are bounded: a name of 1 to 200 characters, unique within your account without regard to letter case; a purpose of up to 4,000 characters; an identifier of 1 to 400 characters; a user name of up to 320 characters; a client id and a tenant id of up to 450 characters each; each tag 1 to 64 characters, at most 20 tags on a Persona; and a secret of up to 32 KiB of UTF-8, with no control characters other than tab, line feed and carriage return. A name, an identifier, a user name, a client id, a tenant id and a tag must each contain some visible text.

A list's expiry horizon is bounded: personas_list takes expiresWithinDays from 0 to 3,650, in whole days.