# SquidShell developer quickstart

Status: public read-only endpoints and the E2EE agent vault beta are available. Use the SDK/CLI for secret values; do not send plaintext to the API.

## Public API

Base URL: https://api.squidshell.com/v1

No authentication is needed for these read-only requests:

```sh
curl --fail-with-body https://api.squidshell.com/v1/desktop-clients
curl --fail-with-body 'https://api.squidshell.com/v1/notices?notice_type=release&page=1&page_size=5'
```

Successful responses use `{ "message_code": 100, "message": "success", "data": ... }`. Inspect both the HTTP status and the response envelope.

`desktop-clients` returns platform download URLs. Use the `osx`, `windows`, `deb` and `rpm` fields independently; the top-level version does not mean every platform has that version. A null link means no download is provided for that platform.

Query the downloads endpoint for current platform versions. The macOS installer supports macOS 13+ on Apple Silicon and Intel. Releases older than macOS 1.0.38 require a manual installation to move to the current updater feed.

## Agent authentication — beta

The web entry point is `/dashboard/api-keys`. Each agent gets a separate key with an expiry date, permissions and explicitly selected vaults. Key values are displayed only on creation; only a hash is retained by the authentication service.

Check an agent credential with:

```sh
curl --fail-with-body https://api.squidshell.com/v1/agent/me \
  -H "Authorization: Bearer $SQUIDSHELL_API_KEY"
```

Never put a real key in a URL, chat prompt, source file, example, screenshot or log. Supply it from the calling process's secret store. Agent keys cannot issue other keys or access account-management APIs.

## End-to-end encrypted vault — beta

The selected model is E2EE. The SDK encrypts entry names and values on the client; the API stores an opaque AES-256-GCM snapshot. Its authentication key and local vault decryption key are independent. Existing desktop SSH credential storage is unchanged.

Install with `npm install squidshell-sdk@0.1.0` (Node.js 24+, beta). Import from `squidshell-sdk` and `squidshell-sdk/keyfile`. CLI: `npx --no-install squidshell-vault`.

Use [the interactive guide](https://www.squidshell.com/developers#vault) for step-by-step CLI/Node.js examples, or [the Markdown SDK/CLI reference](https://www.squidshell.com/developers/e2ee.md) for automated reading. [npm package](https://www.npmjs.com/package/squidshell-sdk).

The interactive authentication simulator uses no real credential and sends no request. Its allowed/denied results explain scope, explicit grants, expiry and revision checks. The public API runner makes real anonymous GET requests only. The encryption demo operates locally on fixed fictional values.

Implemented transport routes:

- `GET /v1/agent/vaults/{vault_id}/content`: encrypted snapshot; requires `vault:read` and a grant to that vault.
- `PUT /v1/agent/vaults/{vault_id}/content`: encrypted snapshot only; requires `vault:write`, a grant and `If-Match: "revision"`. Use the SDK; never send plaintext.

A read/write key can replace or rotate its granted vault. Missing scope returns HTTP 403; an ungranted vault returns HTTP 404. A conflict returns HTTP 409 without overwriting. A revoked/expired API credential is rejected. Revocation cannot erase already copied data. No 1Password compatibility or equivalent security certification is claimed.