create retrieval key
Create an organization-owned read-only key scoped to this prompt. Return its full secret only in the initial 201 response and persist only a cryptographic hash; never store the secret in an idempotency receipt. Within the receipt retention period, a retry with the same idempotency key and body creates no duplicate and returns 409 secret_unavailable with the existing key metadata in error.details.key, without a secret. If the original response was lost, explicitly revoke that key and create a replacement using a new idempotency key. Different-body reuse fails idempotency_conflict. No automatic expiry. Rotation creates a new key, then explicitly revokes the old one.
/api/v1/organizations/{organizationId}/prompts/{promptId}/keysAuthorization
ManagementOAuth managementUser-based Clerk OAuth. CLI is a public Authorization Code client using S256 PKCE and browser loopback redirect. Hosted MCP uses resource-bound OAuth. Verify issuer, token type, intended audience/resource, scopes, live membership and current role. Do not forward arbitrary OAuth tokens into Convex session JWT auth. OAuth URLs below are placeholders for deployment configuration.
In: header
Scope: management
Path Parameters
Permanent organizationId; selected organization must be authorized for the current user.
Permanent promptId; selected organization must be authorized for the current user.
Header Parameters
Management writes: scoped to OAuth user+client+organization+operation. Store request digest and response for at least 24 hours. Same key/body replays original response, including after completion; different body fails idempotency_conflict. Exception: create_retrieval_key stores a non-secret receipt referencing the created key, never its secret. Same-key/body retries return 409 secret_unavailable with existing key metadata and do not create another key. Evaluation creation must not execute twice.
8 <= length <= 128Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/organizations/string/prompts/string/keys" \ -H "Idempotency-Key: stringst" \ -H "Content-Type: application/json" \ -d '{ "name": "string" }'{ "key": { "id": "string", "name": "string", "prefix": "string", "createdAt": "2019-08-24T14:15:22Z", "lastUsedAt": "2019-08-24T14:15:22Z", "revokedAt": "2019-08-24T14:15:22Z" }, "secret": "string"}list retrieval keys GET
Uses the selected organization and the authenticated user’s current permissions. Applies the same setup and archive rules as the dashboard.
revoke retrieval key DELETE
Explicitly revoke a retrieval key. Subsequent server requests fail authorization, including conditional requests. Already fetched content cannot be recalled.