# Authentication, permissions and safe credentials

Canonical URL: https://sosoapi.ai/docs/authentication

Sign in with OAuth for an agent, use a personal access token on your server, and choose the permissions each caller needs.

## 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](https://sosoapi.ai/docs/api)

## 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](https://sosoapi.ai/docs/api)