---
title: "Create a secret handoff"
method: POST
path: "/v1/secret-handoffs"
tags: ["secret-handoffs"]
---

# Create a secret handoff

`POST /v1/secret-handoffs`

## Request

- Base URL: `https://api.typenode.ai`
- URL: `https://api.typenode.ai/v1/secret-handoffs`
- Auth: HTTP bearer

## Request body

- union
  - object
    - `kind` 'oauth_app_registration', required
    - `payload` object, required
      - `additional_body_params` object
      - `allowed_scopes` string[], required
      - `already_revoked_answer` object
        - `error` string, required
        - `status` integer, required
      - `auth_params` object
      - `authorize_url` string, required
      - `client_id` string
      - `granted_scope_separator` ' ' | ','
      - `id` string, required
      - `name` string, required
      - `option` object
        - `application` string, required
        - `authentication_option` string, required
      - `pkce_required` boolean
      - `revocation_url` string
      - `scope_separator` ' ' | ','
      - `token_content_type` 'json' | 'form'
      - `token_endpoint_auth_method` 'basic' | 'header' | 'body' | 'none'
      - `token_url` string, required
  - object
    - `kind` 'secret_set', required
    - `payload` object, required
      - `environment` string, required
      - `expected_version` integer
      - `field` object
        - `application` string, required
        - `authentication_option` string, required
        - `field` string, required
      - `name` string, required
      - `permissions` string[]
      - `write_mode` 'create' | 'replace', required
  - object
    - `kind` 'access_key_create', required
    - `payload` object, required
      - `capabilities` string[], required
      - `environment_ids` string[]
      - `expires_at` string, date-time, nullable
      - `name` string, required
      - `resources` object[]
        - `resource_id` string, uuid, required
        - `resource_type` string, required
  - object
    - `kind` 'credential_connect', required
    - `payload` union, required
      - object
        - `environment` string, required
        - `mode` 'connect', required
        - `name` string, required
        - `oauth_app` string, required
        - `scopes` string[], required
      - object
        - `credential_id` string, uuid, required
        - `environment` string, required
        - `mode` 'reconnect', required
        - `name` string, required
        - `oauth_app` string, required
        - `scopes` string[], required
  - object
    - `kind` 'variable_set', required
    - `payload` object, required
      - `environment` string, required
      - `expected_version` integer
      - `field` object
        - `application` string, required
        - `authentication_option` string, required
        - `field` string, required
      - `name` string, required
      - `permissions` string[]
      - `prefill` string
      - `write_mode` 'create' | 'replace', required

## Response `201`

The exact request's trusted entry link, submission deadline and reviewed-intent coordinates.

- CreateSecretHandoffResponse
  - `completion_url` string, uri, required
  - `expires_at` string, date-time, required
  - `intent_revision` integer, required
  - `operation_id` string, uuid, required

## Other responses

- `400`: The staged handoff payload is invalid.
- `401`: Authentication required.
- `403`: The caller lacks authority for the requested handoff kind.
- `502`: The handoff store or kind-specific validation dependency returned an invalid result.
- `503`: The handoff service is temporarily unavailable.
- `504`: The handoff service timed out.
- `default`: An error occurred (RFC 9457 problem+json).

## Changes

- **2026-10-20** `9b943024aa98`: 1 info
  - added the new optional request property `oneOf[subschema #1]/payload/already_revoked_answer`

[Operation history](https://skmtc.dev/typenode/apis/typenode-management-api/changes/v1/secret-handoffs/post.md)

---

[API](https://skmtc.dev/typenode/apis/typenode-management-api.md) · [All operations](https://skmtc.dev/typenode/apis/typenode-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/typenode/apis/typenode-management-api/revisions/9b943024aa98?raw)