Auth — credentials & external users

When to use bare credential vs externalUserId

Auth

Credential

PERSONA_CREDENTIAL is "<keyId>.<secret>" minted in Developer Studio → Project → Credentials. It is a server secret — sent as Authorization: Bearer <keyId>.<secret>.

Never bundle it. See .

Dual-mode rule

Call	Set `externalUserId`?	Why
`agents.create`, `providers.create`, `auditLogs.list`	No — control-plane (Project-owned)	Uses machine principal
`threads.`, `files.`, `chat.stream`, `memory.*` (when scope externalUser)	Yes — per-request `new PersonaClient({…, externalUserId: yourUserId })`	Thread/file/chat belongs to that end user

const admin = new PersonaClient({ baseUrl, credential }); // control-planeconst user  = new PersonaClient({ baseUrl, credential, externalUserId: req.user.id }); // runtime-plane

const admin = new PersonaClient({ baseUrl, credential }); // control-planeconst user  = new PersonaClient({ baseUrl, credential, externalUserId: req.user.id }); // runtime-plane

See .

`whoami()`

Side-effect-free auth check.

Types — sdk v0.9.0

Chat streaming