Developer lifecycle
Onboarding
controlled developer access onboarding starts with a Torq-approved invitation, not an unauthenticated public
signup. Your server calls POST /v1/organizations with the invitation, an idempotency key, a
declared browser origin, and an organization-owner wallet. The response creates one test
organization, first application, sandbox record, and one-time initial credentials.
Record the non-secret organization and application IDs. Transfer the secret key directly to a server-side secret manager before the response is discarded. Configure the publishable key only at the declared browser origin. The quickstarts page includes the exact bootstrap contract.
Key rotation and revocation
All application keys are persisted as hashes. Torq shows a value once at creation or rotation and cannot show it again.
- List redacted metadata with GET /v1/keys.
- Create a least-privilege replacement with POST /v1/keys, or atomically rotate a known key.
- Deploy the replacement to the correct server or approved browser origin.
- Observe authenticated usage and audit evidence.
- Revoke a compromised or retired key.
Never rotate a key by placing its replacement in a URL, chat transcript, source repository, or browser local storage. A rotation is state-changing: use a fresh idempotency key and treat a network timeout as ambiguous until you inspect the canonical key metadata or audit log.
Permissions
The effective permission is the intersection of application scope, key scope, wallet-session scope, current chain, canonical entity role, and any required on-chain or timelock authority. A key can never grant a role that the canonical authority state does not grant.
Use narrow scopes. For example, an event consumer may need events:read; a webhook manager needs
webhooks:write; a vault-deployment integration also needs the current Asset Manager authority.
Review the authentication guide before adding any write scope.
Rate limits and retries
The v1 boundary emits x-ratelimit-limit, x-ratelimit-remaining,
x-ratelimit-reset, and x-request-id. Do not hard-code a quota. On 429, respect Retry-After
where returned and retry only when the error says retryable: true.
For a state-changing request, keep the same idempotency key only when the body is byte-for-byte the
same logical operation. A changed request with an old key is rejected with idempotency_conflict.
For a signed transaction, do not broadcast a second transaction to compensate for delayed indexing;
register the submitted hash and wait for the tracked lifecycle.
Troubleshooting sequence
Use the request ID, workflow request ID, transaction hash, delivery ID, and stream cursor when contacting the approved preview support channel. These identifiers are diagnostic metadata; do not include a secret key, session token, raw signature, or webhook secret.