Developer lifecycle
Preview onboarding, credential rotation, permissions, rate limits, and practical troubleshooting.
Onboarding
Developer Preview 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
| Symptom | First check | Safe next action |
|---|---|---|
401 invalid_credentials | Environment, key kind, and application status | Rotate only after identifying the application/key metadata; never paste the secret into the browser explorer |
403 wrong_wallet or role block | Wallet session address, chain, entity role | Recreate the one-time session and inspect canonical authority; do not spoof an address in request JSON |
409 stale or blocked workflow | Freshness evidence and blockedReasons | Re-read canonical state and prepare a new workflow; do not reuse stale intents |
429 | Response headers and Retry-After | Back off with jitter; avoid parallel retries for one idempotency key |
| Transaction is mined but UI is unchanged | Tracked workflow or transaction status | Wait for indexed, persisted_visible, then final_success and re-read the resource |
| Duplicate webhook | Delivery ID and event ID in your durable inbox | Acknowledge only after deduplication; replay is safe only inside its retained window |
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.