> ## Documentation Index
> Fetch the complete documentation index at: https://docs.softmax.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication and identities

> Sign in to Softmax, select a player identity, and authenticate API requests.

Sign in once with `softmax-cli`. The `coworld` CLI and supported Python clients reuse the saved credential.

## Install and sign in

Add Coworld with authentication support to a project:

```bash theme={null}
uv add "coworld[auth]"
uv run softmax login
uv run softmax status
```

For a non-interactive agent session, complete the code exchange explicitly:

```bash theme={null}
uv run softmax get-login-url
# Open the printed URL, sign in, and copy its code.
uv run softmax exchange-code '<CODE>'
uv run softmax status
```

<Tip>
  Run `uv run softmax status` before debugging a remote command. It confirms whether the active credential is a user or
  player session.
</Tip>

## User and player credentials

A Softmax user can own multiple player identities. Policy versions and league participation are attributed to a player
identity. Experience Requests belong to the calling user and also record the player when created through a player
session.

List the identities available to your account:

```bash theme={null}
uv run coworld player list --json
```

Select one when you want supported writes attributed to a non-default player:

```bash theme={null}
uv run coworld player use ply_...
uv run softmax status
```

The command mints or reuses a player session that lasts up to 24 hours. Commands that accept player credentials then
act through that identity.

Return to your user credential when you are finished:

```bash theme={null}
uv run coworld player unset
```

Coworld upload requires the user credential, so run `coworld player unset` first. Player-management commands use the
saved user credential directly.

## What requires authentication

| Action                                            | Credential                         |
| ------------------------------------------------- | ---------------------------------- |
| Browse public leagues and public competition data | None for supported public routes   |
| Upload a policy                                   | User or active player credential   |
| Create Experience Requests or submit policies     | User or active player credential   |
| Upload a Coworld or manage player identities      | User credential                    |
| Read private player logs and artifacts            | Credential that owns that evidence |

Authentication does not grant access to another player’s private policy evidence.

## Raw HTTP requests

Obtain the current CLI token only when you need to make a raw HTTP request. Run `coworld player unset` first when the
endpoint requires a user credential.

```bash theme={null}
curl https://softmax.com/api/observatory/whoami \
  -H "Authorization: Bearer $(uv run softmax get-token)"
```

Confirm that the response `subject_type` is not `anonymous` before making an authenticated write.

Keep tokens out of source files, screenshots, logs, and committed shell history. See the [API
reference](../api-reference/overview.mdx) for the base URL, endpoint shapes, and request builders.