API keys

An account holds up to 5 active API keys at once. All of them share the same account quota — extra keys are for separating apps, not for buying more capacity. See Authentication for what a key is. Everything on this page is on https://dash.square1.dev and accepts either the ws-session cookie or a Bearer API key — see Account API overview.

List keys — `GET /api/user/me/keys`

curl https://dash.square1.dev/api/user/me/keys \
  -H "Authorization: Bearer $SQUARE1_API_KEY"

{
  "success": true,
  "data": {
    "keys": [
      {
        "id": 41,
        "label": "risu",
        "key_prefix": "sq-arca-9f3c1a0b",
        "created_at": 1756400000000,
        "last_used_at": 1756486400000,
        "revealable": true,
        "legacy": false
      }
    ],
    "max": 5
  }
}

Active (non-revoked) keys only, oldest first. No plaintext and no hash is ever in this response.

Field	Notes
`id`	Integer. The handle for delete and reveal
`label`	What you named it, or `새 키` if you didn’t. Truncated to 40 characters at creation
`key_prefix`	The first 16 characters of the key — enough to recognize it, not enough to use it. May be `null` on very old rows
`created_at`, `last_used_at`	Epoch milliseconds, not ISO strings. `last_used_at` is `null` until first use, then debounced to at most one write per minute
`revealable`	Whether the plaintext is still recoverable — see below
`legacy`	`true` for `ws-` keys (and for rows with no stored prefix)

revealable is a per-row property, not a global feature flag. Three kinds of row coexist: legacy ws- keys (never revealable), sq-arca- keys issued before key encryption was configured (not revealable), and sq-arca- keys issued after (revealable). Read the flag per key.

max is the account cap. Read it rather than hardcoding 5 — it is the same value that produces key_cap_reached.

Create a key — `POST /api/user/me/keys`

curl -X POST https://dash.square1.dev/api/user/me/keys \
  -H "Authorization: Bearer $SQUARE1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "my-bot"}'

{ "success": true, "data": { "apiKey": "sq-arca-..." } }

label is optional and truncated to 40 characters. Omit it and the key is named 새 키.
apiKey is the only time the plaintext appears in a create response. Store it now.
Requires an active account.

HTTP	`code`	Meaning
401	—	No valid cookie or key
403	`account_unlinked`	Account isn’t `active`; re-verify in the dashboard first
400	`key_cap_reached`	You already hold `max` active keys — revoke one first

Delete a key — `DELETE /api/user/me/keys/:id`

curl -X DELETE https://dash.square1.dev/api/user/me/keys/41 \
  -H "Authorization: Bearer $SQUARE1_API_KEY"

{ "success": true }

:id must be a positive integer; anything else is 400. A key that isn’t yours, or is already revoked, is 404 — the two are not distinguished.

Revocation is immediate. Any client still presenting that key starts getting 401 invalid_api_key on /v1 right away. Nothing stops you from deleting the key you are currently authenticating with.

Reveal a key — `GET /api/user/me/keys/:id/reveal`

Returns the full plaintext of a key you already created, for keys where revealable is true.

curl https://dash.square1.dev/api/user/me/keys/41/reveal \
  -H "Authorization: Bearer $SQUARE1_API_KEY"

{ "success": true, "data": { "key": "sq-arca-..." } }

Rate limit: 30 requests/minute. See Rate limits.
Every successful reveal is written to the account’s audit trail. The audit record holds the key id, never the plaintext.
This is deliberately a separate request rather than a field on the list — the list is fetched on every page load and would otherwise leave plaintext in browser, proxy, and devtools history.

HTTP	`code`	Meaning
400	—	`:id` is not a positive integer
409	`key_not_revealable`	The plaintext is not stored for this key. Not an error condition — legacy and pre-encryption keys are permanently unrecoverable

409 also covers the case where the stored ciphertext exists but can no longer be decrypted. Either way the honest answer is “we don’t have the original”, which is why it is a 409 and not a 500.

Rotate everything — `POST /api/user/me/rotate-key`

The panic button. Revokes every key on the account and issues one fresh key in a single step.

curl -X POST https://dash.square1.dev/api/user/me/rotate-key \
  -H "Authorization: Bearer $SQUARE1_API_KEY"

{ "success": true, "data": { "apiKey": "sq-arca-..." } }

This is not “add a key”. Every existing key — including the one you may have used to make this call — stops working immediately. Use POST /api/user/me/keys for ordinary key management.

Requires an active account (403 account_unlinked otherwise).

60-second cooldown between rotations. Trip it and you get a 429 with no code and no Retry-After:

{ "error": { "message": "잠시 후 다시 시도해 주세요", "type": "rate_limit_exceeded" } }

The replacement key is labeled 기본.
The rotation is audited.

Rotating does not touch your browser sessions. To end those, see Sessions.

Getting started

Core concepts

Guides

Account API

Public data

List keys — `GET /api/user/me/keys`

Create a key — `POST /api/user/me/keys`

Delete a key — `DELETE /api/user/me/keys/:id`

Reveal a key — `GET /api/user/me/keys/:id/reveal`

Rotate everything — `POST /api/user/me/rotate-key`

​List keys — GET /api/user/me/keys

​Create a key — POST /api/user/me/keys

​Delete a key — DELETE /api/user/me/keys/:id

​Reveal a key — GET /api/user/me/keys/:id/reveal

​Rotate everything — POST /api/user/me/rotate-key

List keys — `GET /api/user/me/keys`

Create a key — `POST /api/user/me/keys`

Delete a key — `DELETE /api/user/me/keys/:id`

Reveal a key — `GET /api/user/me/keys/:id/reveal`

Rotate everything — `POST /api/user/me/rotate-key`