Keys
POST /1/keys, GET /1/keys, DELETE /1/keys/:id — create, list and revoke API keys.
POST /1/keys
GET /1/keys
DELETE /1/keys/:idEvery route here requires an admin key. See API keys for what each key type can do, and Scoped tokens for the signing secret a search key returns.
Create a key
POST /1/keystype CreateKeyRequest = {
name: string;
type: 'admin' | 'write' | 'search';
restrictions?: {
indexes?: string[] | null;
referrers?: string[] | null;
ratePerMinute?: number | null;
};
};
type CreateKeyResponse = {
key: KeySummary;
secret: string;
signingSecret: string | null;
};secret and signingSecret are both returned exactly once, at creation — there is no route that reveals either again. signingSecret is null for admin and write keys; only a search key gets one, since it is the key a signed scoped token narrows.
curl -X POST https://api.usesuo.com/1/keys \
-H "x-suo-key: suo_admin_YOUR_KEY" \
-H "content-type: application/json" \
-d '{ "name": "docs widget", "type": "search", "restrictions": { "indexes": ["docs"] } }'{
"key": {
"id": "suokey_8f2c1a94",
"name": "docs widget",
"type": "search",
"display": "suo_search_…7f3a",
"restrictions": { "indexes": ["docs"], "referrers": null, "ratePerMinute": null },
"createdAt": 1732550401123,
"lastUsedAt": null
},
"secret": "suo_search_YOUR_KEY",
"signingSecret": "3q0F...base64url"
}List keys
GET /1/keystype ListKeysResponse = {
keys: KeySummary[];
};
type KeySummary = {
id: string;
name: string;
type: 'admin' | 'write' | 'search';
display: string;
restrictions: { indexes: string[] | null; referrers: string[] | null; ratePerMinute: number | null };
createdAt: number;
lastUsedAt: number | null;
};display is the prefix plus the last four characters (suo_search_…7f3a) — enough to identify the key, never enough to reconstruct it. Neither secret nor signingSecret is returned here.
Revoke a key
DELETE /1/keys/:idReturns 204 No Content on success. Revoking a key keeps its row for audit but evicts it from the lookup cache; the revocation can take up to 60 seconds to reach every edge location — see API keys.
curl -X DELETE https://api.usesuo.com/1/keys/suokey_8f2c1a94 \
-H "x-suo-key: suo_admin_YOUR_KEY"From the CLI
suo keys create --name "docs widget" --type search --index docs --admin-key suo_admin_YOUR_KEY --host https://api.usesuo.com
suo keys list --admin-key suo_admin_YOUR_KEY --host https://api.usesuo.com
suo keys revoke suokey_8f2c1a94 --admin-key suo_admin_YOUR_KEY --host https://api.usesuo.comsuo keys create prints secret with a "shown once" warning, but does not yet print signingSecret — call the route directly (as above) until the CLI is updated to surface it too.