How to get an API key

OtoCo’s MCP server and REST /v1 API share one capability registry. Public tools work with no key. Anything that touches your entities, payments, files, or banking needs an API key.

How to get an API key

Follow these steps once — then paste the key into Cursor, Claude, or any REST client.

Open DashPanel → Developer.
Sign in (connect your wallet if prompted).
Click Create API key (user key).
Copy the full token immediately — it is shown only once. It looks like: otoco_sk_<keyId>_<secret>
Use it as: Authorization: Bearer otoco_sk_…

Treat keys like passwords

Never commit an API key to git or paste it into public chats. If it leaks, revoke it in DashPanel → Developer and create a new one.

Next: connect your agent

After you have a key, follow Connect your AI agent or try a request in the API playground.

Key format


Format	`otoco_sk_<keyId>_<secret>`
Header	`Authorization: Bearer otoco_sk_…` (raw token without `Bearer` is also accepted)
Manage	DashPanel → Developer — create, rotate, revoke

Public vs API-key tools

Access	Header	What you get
Public	None	Discovery, name checks, public entity lookup, Instant/Standalone email checkout
API key	`Authorization: Bearer otoco_sk_…`	Public tools + your entity, document, file, payment, banking, and account tools (per scopes on the key)

Check what your key can do

Call user_me / GET /v1/me to see keyKind and keyScopes for the key you are using.

Scopes

Public capabilities need no scope. These user scopes apply to API keys:

Scope	Grants
(none)	Public discovery tools
`entities:read`	List/get owned entities
`entities:write`	Entity formation checkout
`documents:read`	Document definitions and temp download links
`files:read`	List entity files; temp download links
`files:write`	Delete entity files
`payments:read`	List payments and subscriptions
`payments:write`	Create payment links; cancel subscriptions
`finance:read`	Balances, transactions, notes
`finance:write`	Add/remove transaction notes
`points:read`	Points balance and history
`forms:read`	Available forms and submissions
`forms:write`	Submit entity forms
`banking:read`	EIN / Mercury / Meow / virtual mailing status
`banking:write`	Submit EIN; create Mercury/Meow applications; reset rejected Meow
`user:read`	Profile (`/me`), list own API keys
`user:write`	Revoke own API keys (confirmation-gated)

Security properties

Secret hashed at rest (SHA-256); compared with timingSafeEqual
Full token never stored or returned after creation
Revocable; optional expiry enforced at auth time
Optional IP allowlist (allowedIps) — exact match
Max 10 active user keys per member

Rate limits

Caller	Limit	On exceed
No key (per IP)	30 req/min	`429` + `Retry-After`
API key	120 req/min per key	`429` + `Retry-After`
Auth failures (per IP)	20 req/min	stricter bucket

Confirmation-gated actions

These tools require a preview call, then confirm: true on a second call after your explicit approval:

entities_creation_checkout, entities_series_box_checkout, entities_byoe_checkout
payments_create_link, subscriptions_cancel
files_delete, forms_submit, user_keys_revoke
banking_ein_submit, banking_mercury_apply, banking_meow_apply, banking_meow_reset

Money-moving confirms must also pass back paymentAttemptId and confirmationToken from the preview.

REST response shape

Success:

{ "ok": true, "data": { } }

Error:

{ "ok": false, "error": "..." }

Status	Meaning
`400`	Invalid input
`401`	Invalid API key
`403`	Missing scope or not authorized for the entity
`404`	Not found
`429`	Rate limit exceeded
`500`	Internal error

How to get an API key