> This page is also available as Markdown: append .md to its URL. The full index of Sikaru docs is at https://docs.sikaru.ai/llms.txt. Code examples use only operations from the public API reference at https://docs.sikaru.ai/api-reference.

# Authentication

Authentication summary for this page:

1. Environment variables: `SIKARU_BASE_URL` (hosted: `https://api.sikaru.ai`), `SIKARU_PROJECT_ID`, `SIKARU_API_KEY` (inject from a secret manager).
2. Python SDK: `SikaruApi(api_key=..., base_url=..., timeout=20)` from `sikaru_api`; pass the project ID explicitly to operations.
3. REST: send `Authorization: Bearer <your-project-api-key>`. Test read: `GET $SIKARU_BASE_URL/v1/projects/$SIKARU_PROJECT_ID/managed-agents`. An empty successful listing means authorized with no agents.
4. Terminal device sign-in: `sikaru auth login` (separate from dashboard sign-in). The CLI also reads `SIKARU_API_KEY` or the operating-system keyring.
5. Permissions: `runs:read` (list agents; run status, pending actions, trajectories), `managed_agents:write` (create agent), `runs:create` (start work or request recovery), `events:read` (run events), `tool_results:write` (tool results and approval decisions), `tool_providers:write` (connections and grants), `harness:write` (release decisions). The quickstart needs the first four.
6. Errors: 401 = credential missing, invalid, or wrong endpoint; 403 = project scope or operation permission; 404 = resource ownership or identifiers.

Authenticate application requests with a Sikaru **project API key**. Dashboard sign-in sets up your browser session. Use `sikaru auth login` separately for device sign-in in the terminal.

Signed-in user tokens carry the verified runner identity needed for personal connections. Project keys cannot impersonate a user through request labels.

| Who is calling            | How it authenticates                                      |
| ------------------------- | --------------------------------------------------------- |
| A person in the dashboard | Dashboard sign-in                                         |
| A person in the terminal  | `sikaru auth login` (device sign-in), or `SIKARU_API_KEY` |
| Your application backend  | Project API key                                           |
| A local-compute executor  | Restricted attachment credentials                         |

## Prepare your environment

#### Get your project ID and API key

Sign in to the [Sikaru platform](https://sikaru.ai), select the intended project, and get its project ID and API key. Use the API URL for your environment. The hosted API uses `https://api.sikaru.ai`.

#### Set environment variables

```sh
export SIKARU_BASE_URL="https://api.sikaru.ai"
export SIKARU_PROJECT_ID="YOUR_PROJECT_ID"
# Inject SIKARU_API_KEY using your deployment's secret manager.
```

`SIKARU_PROJECT_ID` is a value used by these examples; pass it explicitly to SDK operations. The SDK examples also pass the base URL and key explicitly.

#### Create a client

```python
import os
from sikaru_api import SikaruApi

project = os.environ["SIKARU_PROJECT_ID"]
client = SikaruApi(
    api_key=os.environ["SIKARU_API_KEY"],
    base_url=os.environ["SIKARU_BASE_URL"],
    timeout=20,
)
```

#### Test a REST request

For REST requests, send `Authorization: Bearer <your-project-api-key>`. For example, this read lists the project's agents:

```sh
curl --fail-with-body --silent --show-error \
  "$SIKARU_BASE_URL/v1/projects/$SIKARU_PROJECT_ID/managed-agents" \
  -H "Authorization: Bearer $SIKARU_API_KEY"
```

> **Check**
>
> An empty successful listing means the request was authorized but there are no agents to display. Continue with the [Quickstart](/get-started/quickstart) to create one.

## Permissions by task

| Task                                                               | Required permission    |
| ------------------------------------------------------------------ | ---------------------- |
| List agents; inspect run status, pending actions, and trajectories | `runs:read`            |
| Create an agent                                                    | `managed_agents:write` |
| Start work or request recovery                                     | `runs:create`          |
| Read run events                                                    | `events:read`          |
| Submit a tool result or approval decision                          | `tool_results:write`   |
| Manage connections and grants                                      | `tool_providers:write` |
| Make release decisions                                             | `harness:write`        |

A valid key may still lack permission for a particular operation. Use a key for the intended project and grant only the operations your integration needs. The first-agent quickstart needs the first four permissions above.

## Keep the key on your backend

A browser or mobile client should call your application's authenticated backend. Your backend checks the user's access, selects the tenant and user identifiers, and calls Sikaru.

> **Warning**
>
> Do not include a project API key in a browser bundle, prompt, uploaded file, or public issue.

For the CLI, inject `SIKARU_API_KEY` or use its operating-system keyring. See [CLI automation](/sdks-and-cli/cli-automation) for login and credential-source behavior. Local-compute executors use restricted attachment credentials; do not pass the controlling project key into the execution sandbox.

## Diagnose access failures

| Status  | What to check                                                                                                |
| ------- | ------------------------------------------------------------------------------------------------------------ |
| **401** | The credential exists, is valid, and reaches the intended API endpoint.                                      |
| **403** | Project scope and the operation's permission.                                                                |
| **404** | Resource ownership and identifiers. A resource outside the caller's scope may be unavailable to that caller. |

Changing an ID or retrying a mutation is not a remedy for an access failure. See [Troubleshooting](/help/troubleshooting) for other failure cases.

## Next steps

#### [Run your first agent](/get-started/quickstart)

Use your key to create an agent and run a task.

#### [CLI automation](/sdks-and-cli/cli-automation)

Login and credential sources for scripts and CI.

#### [Troubleshooting](/help/troubleshooting)

Diagnose other failure cases.