# Authentication

Use the right credential for your workspace, your API client or one outside agent.

## Choose Your Access Path

**Browser**

Sign in using the account flow configured by the installation. Personal token-based setups use developer-token entry.

**API client**

A bearer token issued by the server operator, bound to a workspace and permissions.

**Outside agent**

An owner-issued grant key for authorized turns. It is separate from an owner API token.

The website does not issue a public hosted API key. Use your installation’s API address and credentials.

[Configure a personal API](/docs/self-hosting#docs-self-hosting-api)

## Authenticate an API Request

Set your server address and EXULANICA_TOKEN to the token issued by its operator. Keep the credential outside source files and shared examples.

```bash
export EXULANICA_API_URL="http://127.0.0.1:8000"
# Set EXULANICA_TOKEN privately to your workspace token.
curl --fail-with-body "$EXULANICA_API_URL/worlds" \
  -H "Authorization: Bearer $EXULANICA_TOKEN"
```

A successful response lists the worlds in that token’s workspace and its world-count policy. An empty list is a valid response.

[List worlds: parameters and response](/docs/world-api/list-worlds)

## Permissions and World Availability

World reads require `world.read`; world writes require `world.write`. Model calls also depend on their own permissions and spending configuration.

Permission and capability are separate. A token may allow a write while the selected world does not support it, or while a required service is unavailable. Read the world’s capability descriptor before offering an action.

Every request for a world’s content carries its world_id. References outside the token’s workspace return unknown_reference rather than exposing another workspace’s content.

[Read a world’s capabilities](/docs/world-api/capabilities)

## Give an Agent Bounded Access

The world owner issues an expiring grant to decide for named world agents or bring in a visitor body. The key authorizes that grant’s turns. It does not give the agent the owner’s workspace permissions.

Owners can revoke a grant or replace its key. Missed turns and disconnected agents leave the world’s routine in control.

[Issue and use an agent grant](/docs/agents#docs-agents-connect)

## When Access Fails

Check the server address first: the landing site and browser application are not the API server. Then check the credential’s workspace, permissions, and expiration. For an outside agent, ask the owner whether the grant was revoked or its key replaced.

[Errors and Recovery](/docs/errors)