Authentication - Shanone Documentation

API keys

Every external request to Shanone — whether over the MCP server or the REST API — authenticates with an API key in the form:

sh_xxxxxxxxxxxxxxxx

Send it as a bearer token:

Authorization: Bearer sh_xxxxxxxxxxxxxxxx

X-API-Key: sh_xxxxxxxxxxxxxxxx is also accepted as an alternative header.

The plaintext key is shown exactly once, at creation time. Shanone only stores a hash afterward — if you lose it, revoke it and create a new one.

Creating a key

Go to app.shanone.ai and sign in.

Open API Keys

Go to Settings → API Keys.

Create a key

Click Create API Key, give it a descriptive name, and choose an expiration. The default is 30 days.

Copy the key

Click Create and copy the plaintext key. Save it securely before closing the dialog; it cannot be displayed again.

Expiration

Choose how long a key can be used when you create it:

Option	Lifetime
7 days	7 days after creation
30 days (default)	30 days after creation
60 days	60 days after creation
90 days	90 days after creation
Custom	A whole number of days from 1 to 366
Never	No expiration; valid until revoked or deleted

The lifetime starts when Shanone creates the key, using the server’s clock. One day means 24 hours. Using a key does not extend its lifetime. The creation confirmation and API Keys list show the expiration date and time, including the time zone.

Existing keys created without an expiration remain non-expiring. The 30-day default applies to new keys; it does not add an expiration to existing keys. Choose Never explicitly when creating a new non-expiring key.

When a key expires

At the expiration time, the key stops authenticating new requests to the REST API and MCP server. Expired keys remain in the API Keys list with an Expired status.

Connection	Response for an expired key
REST API	HTTP `401`, with `detail: "Invalid or expired API key"`
Direct MCP endpoint	HTTP `401`, with `error: "invalid_api_key"`

You cannot extend a key’s lifetime after creation or reactivate an expired or revoked key. Create a new key and update every client, environment variable, or secret that used the old one. Follow Rotating keys before expiration to avoid interruptions. Expiration and revocation apply to new authentication checks. They do not cancel work or streams that have already been authenticated.

Scoping a key

Every key can optionally be restricted beyond the defaults:

Setting	Default	Notes
`permissions`	All permissions	Optionally restrict to a subset — see the table below
`rate_limit.requests_per_minute`	60	Configurable 1–1,000
`rate_limit.requests_per_day`	10,000	Configurable 1–1,000,000
`allowed_ips`	Any IP	Optionally restrict to a list of allowed source IPs
Expiration	30 days	Choose a preset, Custom (1–366 days), or Never; see Expiration

Available permissions values:

Permission	Description
`tasks:create`	Create/execute actions
`tasks:read`	Read execution status
`tasks:cancel`	Cancel in-flight executions
`tasks:messages`	Send follow-up messages within a session
`conversations:read`	Read conversation/session history
`integrations:read`	Read connected integrations

A key with no permissions specified has full access. Scope keys down for anything you’re embedding in a script or service you don’t fully trust.

The direct MCP endpoint needs one more thing

If you connect straight to https://app.shanone.ai/mcp (Streamable HTTP) instead of going through Shanone’s local stdio proxy, you also need your organization ID as a second factor, sent as X-Org-Id (or ?org_id= in the URL as a fallback for clients that can’t set custom headers):

Authorization: Bearer sh_xxxxxxxxxxxxxxxx
X-Org-Id: org_xxxxxxxxxxxxxxxx

This composite check means a leaked API key alone isn’t sufficient to call your tools over the direct endpoint — an attacker would also need your organization ID. The REST API (/api/v1/tools/... etc.) and the local stdio proxy do not require this second factor; they authenticate with the API key alone.

Example requests

cURL
Python
JavaScript

curl "https://app.shanone.ai/api/v1/tools/search?query=create+github+issue" \
  -H "Authorization: Bearer sh_xxxxxxxxxxxxxxxx"

import requests

headers = {"Authorization": "Bearer sh_xxxxxxxxxxxxxxxx"}
response = requests.get(
    "https://app.shanone.ai/api/v1/tools/search",
    params={"query": "create github issue"},
    headers=headers,
)

const response = await fetch(
  "https://app.shanone.ai/api/v1/tools/search?query=create+github+issue",
  { headers: { Authorization: "Bearer sh_xxxxxxxxxxxxxxxx" } }
);

Rate limits

Response	Meaning
`429` with `error: "rate_limit_exceeded"`	You exceeded `requests_per_minute` or `requests_per_day` for this key
`Retry-After` header	Seconds to wait before retrying

Raise a key’s limits from Settings → API Keys if you’re consistently hitting them.

Key management

Rotating keys

Create a new key

From Settings → API Keys, create a replacement before the current key expires and choose its expiration.

Update your clients/scripts

Swap the new key in wherever the old one was configured.

Revoke the old key

Once you’ve confirmed the new one works.

Revoking vs. deleting

To revoke an active key, open its … menu in Settings → API Keys, select Revoke, and confirm. New authentication attempts are rejected as soon as revocation completes. The key remains in the list with a Revoked status so you can keep its record. Delete removes the key’s record and also prevents further authentication. Neither operation can be undone. Replace a key in your clients before revoking or deleting it if they still need access. Revoke a key immediately if you suspect it has been exposed.

Security best practices

Use environment variables

Never hardcode a key in a committed config file or source file.

Scope to what's needed

Restrict permissions and allowed_ips, and choose a lifetime that matches how long the key is needed.

One key per machine/agent

So you can revoke individually without breaking everything else.

Rotate periodically

Replace keys before they expire. Revoke exposed or unused keys, including non-expiring ones.

​API keys

​Creating a key

​Expiration

​When a key expires

​Scoping a key

​The direct MCP endpoint needs one more thing

​Example requests

​Rate limits

​Key management

​Rotating keys

​Revoking vs. deleting

​Security best practices

Use environment variables

Scope to what's needed

One key per machine/agent

Rotate periodically

API keys

Creating a key

Expiration

When a key expires

Scoping a key

The direct MCP endpoint needs one more thing

Example requests

Rate limits

Key management

Rotating keys

Revoking vs. deleting

Security best practices