Authentication, permissions and safe credentials

Choose a credential for the caller

For an agent, use browser OAuth: the user signs in and chooses access, and the CLI stores and refreshes its credentials. For a backend script or CI job, supply a personal access token through VICKY_API_KEY. Keep credentials out of browser code, public repositories, prompts, screenshots and shared logs.

The HTTP examples use SOSOAPI_ACCESS_TOKEN as a server-side environment variable for the Bearer value. It is an example variable, not a CLI setting. Check the credentials listed for each operation; personal access tokens cannot manage API keys.

npx sosoapi auth login

npx sosoapi auth status

npx sosoapi auth logout

• Complete API reference

Scope and capabilities

Each request checks workspace membership and the role required for that operation. Delegated OAuth also limits access to the workspaces and capabilities the user selected. agent:operate covers reading and preparation, agent:publish covers scheduling and publishing, and agent:engage covers community writes. Managing API keys requires a separate grant.

A personal access token is limited by its owner’s role and any stored capability or workspace restrictions. Choose only the access your integration needs; omitting optional limits can leave a key with broad access. Core and full profiles change the visible tool list, not permissions. Publishing access continues within its granted scope without a new browser approval for every post.

Credential storage and revocation

The CLI stores credentials in your operating system’s keychain when available, or in a local file readable only by its owner. OAuth access tokens last one hour and are refreshed by the sign-in flow. Use auth status to diagnose a connection rather than copying the credential file.

Revoke a device or authorization in Settings → Agents & API Access, or run auth logout to sign out the current local device. This stops future access. It does not undo published posts or cancel schedules already accepted by SosoAPI; check and manage those separately.

Authentication bootstrap endpoints

The four agent-auth endpoints document the sign-in protocol. Use the supported CLI or a remote OAuth client to sign in; these endpoints are not available through api post. Config, request, session and revoke-current accept different credentials and fields. Follow each endpoint’s schema and keep session credentials out of output and logs.

• Authentication endpoint reference