Skip to navigation
Get started

Authentication

Authenticate your backend with a project API key, choose the permissions each task needs, and diagnose 401, 403, and 404 responses.
View as Markdown

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 callingHow it authenticates
A person in the dashboardDashboard sign-in
A person in the terminalsikaru auth login (device sign-in), or SIKARU_API_KEY
Your application backendProject API key
A local-compute executorRestricted attachment credentials

Prepare your environment

1

Get your project ID and API key

Sign in to the Sikaru platform, 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.

2

Set environment variables

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.

3

Create a client

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,
)
4

Test a REST request

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

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

An empty successful listing means the request was authorized but there are no agents to display. Continue with the Quickstart to create one.

Permissions by task

TaskRequired permission
List agents; inspect run status, pending actions, and trajectoriesruns:read
Create an agentmanaged_agents:write
Start work or request recoveryruns:create
Read run eventsevents:read
Submit a tool result or approval decisiontool_results:write
Manage connections and grantstool_providers:write
Make release decisionsharness: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.

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 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

StatusWhat to check
401The credential exists, is valid, and reaches the intended API endpoint.
403Project scope and the operation’s permission.
404Resource 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 for other failure cases.

Next steps

Run your first agent

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

CLI automation

Login and credential sources for scripts and CI.

Troubleshooting

Diagnose other failure cases.