Skip to main content

​
What are activities?

Activities are requests to create, modify, or use resources within Turnkey. Submission endpoints are always prefixed with /public/v1/submit.
  • Policy enforcement: Activities are subject to consensus or condition enforcement via the policy engine.
  • Optimistic execution: Activities execute optimistically synchronous — if possible, the request completes synchronously; otherwise it falls back to asynchronous processing. Your services should account for this by checking the activity status in the response:
    • ACTIVITY_STATUS_COMPLETED: The activity succeeded and the result field is populated.
    • ACTIVITY_STATUS_FAILED: The activity failed and the failure field contains the reason.
    • ACTIVITY_STATUS_CONSENSUS_NEEDED: More signatures (votes) are required to process the request.
    • ACTIVITY_STATUS_PENDING: The request is processing asynchronously.
  • Approval expiration: Activities do not expire. However, when an activity is submitted, the requester’s submission counts as the first approval and starts a 24-hour window. If the activity is not resolved within that window, existing approvals expire and must be re-submitted. This applies both while the activity is in ACTIVITY_STATUS_CONSENSUS_NEEDED awaiting votes, and in ACTIVITY_STATUS_AUTHENTICATORS_NEEDED awaiting MFA factors.
  • Status updates: Poll get_activity with the activity.id, or re-submit the original request (see idempotency below).
  • Idempotency: The submission API is idempotent. Each request’s POST body is hashed into a fingerprint — any two requests with the same fingerprint return the same activity. To generate a new activity, change the timestampMs value in your request.

​
Signed-request validity

Every activity submission includes timestampMs, a Unix timestamp in milliseconds encoded as a string. At submission time, it must be no more than one hour in the past and no more than five minutes in the future. This applies to signing requests, approvals, rejections, and other activities, including resubmissions. Keep the submitting machine’s clock synchronized and generate the timestamp close to when you submit the request. Turnkey rejects stale requests with activity timestamp is not current and requests too far ahead with activity timestamp is in the future. The submission window is separate from the 24-hour approval window described above. An accepted activity does not expire when its original request becomes too old to submit again. Use Get activity to check its status. Changing timestampMs changes the request fingerprint and creates a new activity; it is not a way to retry the original activity idempotently.

​
Rate limits

Submissions and status queries are subject to API rate limits. Pace requests and use backoff when a limit is exceeded.