---
title: "Create Vault Share Link"
method: POST
path: "/agents/v2/vault/share-links"
tags: ["Vault"]
deprecated: true
---

# Create Vault Share Link

`POST /agents/v2/vault/share-links`

## Request

- Base URL: `https://odyssey.asteroid.ai`
- URL: `https://odyssey.asteroid.ai/agents/v2/vault/share-links`
- Auth: API key in header `X-Api-Key`

> **Deprecated.**

Create a credential request. The item key is derived from name unless itemKey is given. 429 when the user exceeds the creation rate limit.

## Request body

- AgentsVaultCreateVaultShareLinkRequest
  - `description` string: Explanation shown to the recipient of the secret request.
  - `fields` AgentsVaultFieldSpecInput[]: Inline field blueprint. Required when templateId is omitted.
    - `hint` string: Optional guidance shown next to the field, copied from catalog credentials when generating masters.
    - `label` string, required: Human label shown in forms. The field key is UPPER_SNAKE of this label.
    - `required` boolean, required
    - `type` 'username' | 'email' | 'url' | 'phone' | 'text' | 'password' | 'hidden' | 'totp_seed' | 'api_key' | 'card_number' | 'card_expiry' | 'card_cvv' | 'cardholder_name', required: Type of a vault field. Sensitivity is derived from the type: username, email, url, phone, text, card_expiry, and cardholder_name are readable; password, hidden, totp_seed, api_key, card_number, and card_cvv are write-only. There is no separate hidden flag.
  - `itemKey` string: UPPER_SNAKE vault item key. Derived from name when omitted on create. Unique among a profile's attached items, not across the organisation. Stays the same across renames.
  - `kind` 'login' | 'api_key' | 'card' | 'custom': Kind of vault item. Templates and items need at least one field. Completeness is per-field required.
  - `name` string, required: Name of the secret the request creates.
  - `organizationId` string, uuid
  - `steps` AgentsVaultTemplateStep[]: Inline step layout. Only valid with kind and fields; rejected with templateId.
    - `fieldKeys` AgentsVaultFieldKey[], required: Field keys shown on this step, in order. Each field belongs to at most one step. May be empty only when instructions is set.
    - `instructions` string: Markdown shown above the step's fields
    - `key` string, required: Stable identifier. Lower-case slug, unique within the template.
    - `title` string, required
  - `templateId` string, uuid
  - `title` string, required: Title shown to the recipient of the secret request.

## Response `201`

The request has succeeded and a new resource has been created as a result.

- AgentsVaultVaultShareLinkCreated: Create response. token is the raw link secret and recipientUrl carries it. Both are returned once; the server stores only the token's hash.
  - `link` AgentsVaultVaultShareLink, required: A credential request. The recipient opens the link with no session, fills in the values, and one submit creates the vault item. The field blueprint is frozen at create.
    - `actor` CommonActor: Who did something: a person, an API key or one of Asteroid's services. Absent on a record made before actors were stored, on one a system job made, and when the caller may not see who it was.
      - `client` 'web' | 'cli' | 'mcp' | 'astro' | 'sdk': The program a caller used
      - `id` string, required: The person's id, the key's id, or the service's name
      - `kind` 'person' | 'api_key' | 'service', required: The kind of caller that did something
    - `completedAt` string, date-time
    - `createdAt` string, date-time, required
    - `createdBy` string, uuid, required
    - `description` string
    - `expiresAt` string, date-time, required
    - `failedSubmits` integer, required: Submits that resolved this link but did not complete it: invalid values, a dead link, or a lost race.
    - `fields` AgentsVaultFieldSpec[], required
      - `hint` string: Optional guidance shown next to the field, copied from catalog credentials when generating masters.
      - `key` string, required: UPPER_SNAKE field key, unique within a template or item.
      - `label` string, required: Human label shown in forms. The field key is UPPER_SNAKE of this label.
      - `required` boolean, required
      - `type` 'username' | 'email' | 'url' | 'phone' | 'text' | 'password' | 'hidden' | 'totp_seed' | 'api_key' | 'card_number' | 'card_expiry' | 'card_cvv' | 'cardholder_name', required: Type of a vault field. Sensitivity is derived from the type: username, email, url, phone, text, card_expiry, and cardholder_name are readable; password, hidden, totp_seed, api_key, card_number, and card_cvv are write-only. There is no separate hidden flag.
    - `id` string, uuid, required
    - `itemKey` string, required: UPPER_SNAKE vault item key. Derived from name when omitted on create. Unique among a profile's attached items, not across the organisation. Stays the same across renames.
    - `kind` 'login' | 'api_key' | 'card' | 'custom', required: Kind of vault item. Templates and items need at least one field. Completeness is per-field required.
    - `lastFailedSubmitAt` string, date-time
    - `name` string, required: Item name the submit will create.
    - `organizationId` string, uuid, required
    - `resultItemId` string, uuid
    - `status` 'pending' | 'completed' | 'expired' | 'revoked', required: Lifecycle of a share link. expired is derived from expiresAt; the other three are stored.
    - `steps` AgentsVaultTemplateStep[], required
      - `fieldKeys` AgentsVaultFieldKey[], required: Field keys shown on this step, in order. Each field belongs to at most one step. May be empty only when instructions is set.
      - `instructions` string: Markdown shown above the step's fields
      - `key` string, required: Stable identifier. Lower-case slug, unique within the template.
      - `title` string, required
    - `submittedIp` string: Client address the completing submit came from. Set when status is completed.
    - `submittedUserAgent` string: User agent of the completing submit. Set when status is completed.
    - `templateId` string, uuid
    - `title` string, required
    - `updatedAt` string, date-time, required
  - `recipientUrl` string, required: Absolute URL of the page the recipient opens to submit the secret, on this environment's credential-request host. The token is in its fragment.
  - `token` string, required: Raw token for the recipient URL. Returned once.

## Other responses

- `400`: The server could not understand the request due to invalid syntax.
- `401`: Access is unauthorized.
- `403`: Access is forbidden.
- `404`: The server cannot find the requested resource.
- `409`: The request conflicts with the current state of the server.
- `429`: The client address exceeded the rate limit on the public surface. Retry-After carries the wait in whole seconds.
- `500`: Server error

---

[API](https://skmtc.dev/asteroid/apis/agent-service.md) - [All operations](https://skmtc.dev/asteroid/apis/agent-service/llms.txt) - [OpenAPI document](https://skmtc.dev/asteroid/apis/agent-service/revisions/ccc134d1d510?raw)