Depot vault shares

Registers the three share routes.

This page is generated from the Depot route table. Every operation carries the permission it needs and the anchor an agent can link to.

GET /api/v1/vault/shares

GETvault:shareshared facehosteditmspremoteIdempotent

From an MSP console, prefix the path with /api/v1/clients/{clientID} to reach one client.

Source: [object Object]

List vault shares

Parameters

Name	In	Type	Required	Description
clientId	query	string	No
page	query	integer	No	One-based page number. Defaults to 1.
pageSize	query	integer	No	Rows per page, 1 to 200. Defaults to 50.
state	query	string	No
subject	query	string	No
subjectId	query	string	No

Responses

Status	Body	Description
200	application/json, PagedResultShareLinkSummary	Success.
400	application/problem+json, ProblemDetails	One or more validation errors occurred.
401	application/problem+json, ProblemDetails	No signed-in identity.
403	application/problem+json, ProblemDetails	The identity does not hold vault:share.
404	application/problem+json, ProblemDetails	No resource matches.
500	application/problem+json, ProblemDetails	The request failed.
503	application/problem+json, ProblemDetails	This Depot cannot read share links.

200 response body

Field	Type	Description
itemsrequired	array of ShareLinkSummary
items[].clamped	ShareClamp
items[].clamped.expiresInHours	integer
items[].clamped.maxViews	integer
items[].clientIdrequired	string
items[].createdAtrequired	string (date-time)
items[].createdByName	string
items[].deleteAtrequired	string (date-time)
items[].deliveryrequired	string
items[].deliveryAgentId	string
items[].expiresAtrequired	string (date-time)
items[].firstViewedAt	string (date-time) or null
items[].includeTotpCoderequired	boolean
items[].includeUsernamerequired	boolean
items[].kindrequired	string
items[].lastViewedAt	string (date-time) or null
items[].maxViewsrequired	integer
items[].messagerequired	string
items[].publicIdrequired	string
items[].recipientChannel	string
items[].recipientMasked	string
items[].recipientName	string
items[].recipientVerifiedAt	string (date-time) or null
items[].requiresPassphraserequired	boolean
items[].requiresVerificationrequired	boolean
items[].staterequired	string
items[].subjectIdrequired	string
items[].subjectTitlerequired	string
items[].urlrequired	string
items[].viewCountrequired	integer
pagerequired	integer
pageSizerequired	integer
totalrequired	integer

Request samples

curl

# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.
curl -X GET 'https://depot.example.com/api/v1/vault/shares?clientId=<clientId>&page=0&pageSize=0&state=<state>&subject=<subject>&subjectId=<subjectId>' \
  -H 'X-CSRF-Token: <csrf-token>' \
  -H 'Accept: application/json' \
  -b 'outpost_console=<console-session>'

PowerShell

# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.

$headers = @{
    'X-CSRF-Token' = '<csrf-token>'
    'Accept' = 'application/json'
    'Cookie' = 'outpost_console=<console-session>'
}

$response = Invoke-RestMethod `
    -Method Get `
    -Uri 'https://depot.example.com/api/v1/vault/shares?clientId=<clientId>&page=0&pageSize=0&state=<state>&subject=<subject>&subjectId=<subjectId>' `
    -Headers $headers

$response | ConvertTo-Json -Depth 10

Python

# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.

import requests

url = "https://depot.example.com/api/v1/vault/shares"
params = {
    "clientId": "<clientId>",
    "page": "0",
    "pageSize": "0",
    "state": "<state>",
    "subject": "<subject>",
    "subjectId": "<subjectId>",
}
headers = {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
}
cookies = {
    "outpost_console": "<console-session>",
}

response = requests.get(url, params=params, headers=headers, cookies=cookies, timeout=30)
response.raise_for_status()
print(response.json())

Go

// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.
package main

import (
  "fmt"
  "io"
  "log"
  "net/http"
)

func main() {
  req, err := http.NewRequest(http.MethodGet, "https://depot.example.com/api/v1/vault/shares?clientId=<clientId>&page=0&pageSize=0&state=<state>&subject=<subject>&subjectId=<subjectId>", nil)
  if err != nil {
    log.Fatal(err)
  }

  req.Header.Set("X-CSRF-Token", "<csrf-token>")
  req.Header.Set("Accept", "application/json")
  req.AddCookie(&http.Cookie{Name: "outpost_console", Value: "<console-session>"})

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()

  out, err := io.ReadAll(resp.Body)
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(resp.Status, string(out))
}

TypeScript

// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.
// The session cookie is set by signing in. A script cannot set it itself.

const url = new URL("https://depot.example.com/api/v1/vault/shares");
url.searchParams.set("clientId", "<clientId>");
url.searchParams.set("page", "0");
url.searchParams.set("pageSize", "0");
url.searchParams.set("state", "<state>");
url.searchParams.set("subject", "<subject>");
url.searchParams.set("subjectId", "<subjectId>");

const response = await fetch(url, {
  method: "GET",
  headers: {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
  },
  credentials: "include",
});

if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);

C#

// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.

using System;
using System.Net.Http;

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://depot.example.com/api/v1/vault/shares?clientId=<clientId>&page=0&pageSize=0&state=<state>&subject=<subject>&subjectId=<subjectId>");
request.Headers.TryAddWithoutValidation("X-CSRF-Token", "<csrf-token>");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("Cookie", "outpost_console=<console-session>");

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

POST /api/v1/vault/shares

POSTvault:shareshared facehosteditmspremote

From an MSP console, prefix the path with /api/v1/clients/{clientID} to reach one client.

Source: [object Object]

Mint vault share

Request body

Required, sent as application/json.

Field	Type	Description
clientIdrequired	string
deliveryrequired	string, one of link, tray
deliveryAgentIdrequired	string
expiresInHoursrequired	integer
includeTotpCoderequired	boolean
includeUsernamerequired	boolean
kindrequired	string, one of article, credential
maxViewsrequired	integer
messagerequired	string
passphraserequired	string
recipientChannelrequired	string, one of email, sms
recipientContactrequired	string
recipientNamerequired	string
recipientUserIdrequired	string
subjectIdrequired	string

Responses

Status	Body	Description
201	application/json, ShareLinkSummary	Created.
400	application/problem+json, ProblemDetails	The request body is not valid JSON.
401	application/problem+json, ProblemDetails	No signed-in identity.
403	application/problem+json, ProblemDetails	Sharing is turned off for this client. An administrator can turn it on in the documentation settings.
404	application/problem+json, ProblemDetails	No client matches that id.
500	application/problem+json, ProblemDetails	Could not read the credential.
503	application/problem+json, ProblemDetails	This Depot cannot mint share links.

201 response body

Field	Type	Description
clamped	ShareClamp
clamped.expiresInHours	integer
clamped.maxViews	integer
clientIdrequired	string
createdAtrequired	string (date-time)
createdByName	string
deleteAtrequired	string (date-time)
deliveryrequired	string
deliveryAgentId	string
expiresAtrequired	string (date-time)
firstViewedAt	string (date-time) or null
includeTotpCoderequired	boolean
includeUsernamerequired	boolean
kindrequired	string
lastViewedAt	string (date-time) or null
maxViewsrequired	integer
messagerequired	string
publicIdrequired	string
recipientChannel	string
recipientMasked	string
recipientName	string
recipientVerifiedAt	string (date-time) or null
requiresPassphraserequired	boolean
requiresVerificationrequired	boolean
staterequired	string
subjectIdrequired	string
subjectTitlerequired	string
urlrequired	string
viewCountrequired	integer

Request samples

curl

# Sign in first. outpost_console is a session cookie, so send it with every request.
curl -X POST 'https://depot.example.com/api/v1/vault/shares' \
  -H 'X-CSRF-Token: <csrf-token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -b 'outpost_console=<console-session>' \
  --data '{
  "clientId": "string",
  "delivery": "link",
  "deliveryAgentId": "string",
  "expiresInHours": 0,
  "includeTotpCode": false,
  "includeUsername": false,
  "kind": "article",
  "maxViews": 0,
  "message": "string",
  "passphrase": "string",
  "recipientChannel": "email",
  "recipientContact": "string",
  "recipientName": "string",
  "recipientUserId": "string",
  "subjectId": "string"
}'

PowerShell

# Sign in first. outpost_console is a session cookie, so send it with every request.

$headers = @{
    'X-CSRF-Token' = '<csrf-token>'
    'Accept' = 'application/json'
    'Content-Type' = 'application/json'
    'Cookie' = 'outpost_console=<console-session>'
}

$body = @'
{
  "clientId": "string",
  "delivery": "link",
  "deliveryAgentId": "string",
  "expiresInHours": 0,
  "includeTotpCode": false,
  "includeUsername": false,
  "kind": "article",
  "maxViews": 0,
  "message": "string",
  "passphrase": "string",
  "recipientChannel": "email",
  "recipientContact": "string",
  "recipientName": "string",
  "recipientUserId": "string",
  "subjectId": "string"
}
'@

$response = Invoke-RestMethod `
    -Method Post `
    -Uri 'https://depot.example.com/api/v1/vault/shares' `
    -Headers $headers `
    -ContentType 'application/json' `
    -Body $body

$response | ConvertTo-Json -Depth 10

Python

# Sign in first. outpost_console is a session cookie, so send it with every request.

import requests

url = "https://depot.example.com/api/v1/vault/shares"
headers = {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
    "Content-Type": "application/json",
}
cookies = {
    "outpost_console": "<console-session>",
}
payload = {
    "clientId": "string",
    "delivery": "link",
    "deliveryAgentId": "string",
    "expiresInHours": 0,
    "includeTotpCode": False,
    "includeUsername": False,
    "kind": "article",
    "maxViews": 0,
    "message": "string",
    "passphrase": "string",
    "recipientChannel": "email",
    "recipientContact": "string",
    "recipientName": "string",
    "recipientUserId": "string",
    "subjectId": "string",
}

response = requests.post(url, headers=headers, cookies=cookies, json=payload, timeout=30)
response.raise_for_status()
print(response.json())

Go

// Sign in first. outpost_console is a session cookie, so send it with every request.
package main

import (
  "bytes"
  "fmt"
  "io"
  "log"
  "net/http"
)

func main() {
  body := []byte(`{
  "clientId": "string",
  "delivery": "link",
  "deliveryAgentId": "string",
  "expiresInHours": 0,
  "includeTotpCode": false,
  "includeUsername": false,
  "kind": "article",
  "maxViews": 0,
  "message": "string",
  "passphrase": "string",
  "recipientChannel": "email",
  "recipientContact": "string",
  "recipientName": "string",
  "recipientUserId": "string",
  "subjectId": "string"
}`)

  req, err := http.NewRequest(http.MethodPost, "https://depot.example.com/api/v1/vault/shares", bytes.NewReader(body))
  if err != nil {
    log.Fatal(err)
  }

  req.Header.Set("X-CSRF-Token", "<csrf-token>")
  req.Header.Set("Accept", "application/json")
  req.Header.Set("Content-Type", "application/json")
  req.AddCookie(&http.Cookie{Name: "outpost_console", Value: "<console-session>"})

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()

  out, err := io.ReadAll(resp.Body)
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(resp.Status, string(out))
}

TypeScript

// Sign in first. outpost_console is a session cookie, so send it with every request.
// The session cookie is set by signing in. A script cannot set it itself.

const url = "https://depot.example.com/api/v1/vault/shares";

const response = await fetch(url, {
  method: "POST",
  headers: {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
    "Content-Type": "application/json",
  },
  credentials: "include",
  body: JSON.stringify({
    "clientId": "string",
    "delivery": "link",
    "deliveryAgentId": "string",
    "expiresInHours": 0,
    "includeTotpCode": false,
    "includeUsername": false,
    "kind": "article",
    "maxViews": 0,
    "message": "string",
    "passphrase": "string",
    "recipientChannel": "email",
    "recipientContact": "string",
    "recipientName": "string",
    "recipientUserId": "string",
    "subjectId": "string"
  }),
});

if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);

C#

// Sign in first. outpost_console is a session cookie, so send it with every request.

using System;
using System.Net.Http;
using System.Text;

using var client = new HttpClient();

const string body = """
{
  "clientId": "string",
  "delivery": "link",
  "deliveryAgentId": "string",
  "expiresInHours": 0,
  "includeTotpCode": false,
  "includeUsername": false,
  "kind": "article",
  "maxViews": 0,
  "message": "string",
  "passphrase": "string",
  "recipientChannel": "email",
  "recipientContact": "string",
  "recipientName": "string",
  "recipientUserId": "string",
  "subjectId": "string"
}
""";

var request = new HttpRequestMessage(HttpMethod.Post, "https://depot.example.com/api/v1/vault/shares");
request.Headers.TryAddWithoutValidation("X-CSRF-Token", "<csrf-token>");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("Cookie", "outpost_console=<console-session>");
request.Content = new StringContent(body, Encoding.UTF8, "application/json");

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

DELETE /api/v1/vault/shares/{shareId}

DELETEvault:shareshared facehosteditmspremoteIdempotent

From an MSP console, prefix the path with /api/v1/clients/{clientID} to reach one client.

Source: [object Object]

Revoke vault share

Parameters

Name	In	Type	Required	Description
shareId	path	string	Yes	A uuid.

Responses

Status	Body	Description
204	None	Success, with no body.
401	application/problem+json, ProblemDetails	No signed-in identity.
403	application/problem+json, ProblemDetails	The identity does not hold vault:share.
404	application/problem+json, ProblemDetails	No resource matches that id.
500	application/problem+json, ProblemDetails	The request failed.
503	application/problem+json, ProblemDetails	This Depot cannot revoke share links.

Request samples

curl

# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.
curl -X DELETE 'https://depot.example.com/api/v1/vault/shares/<shareId>' \
  -H 'X-CSRF-Token: <csrf-token>' \
  -H 'Accept: application/json' \
  -b 'outpost_console=<console-session>'

PowerShell

# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.

$headers = @{
    'X-CSRF-Token' = '<csrf-token>'
    'Accept' = 'application/json'
    'Cookie' = 'outpost_console=<console-session>'
}

$response = Invoke-RestMethod `
    -Method Delete `
    -Uri 'https://depot.example.com/api/v1/vault/shares/<shareId>' `
    -Headers $headers

$response | ConvertTo-Json -Depth 10

Python

# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.

import requests

url = "https://depot.example.com/api/v1/vault/shares/<shareId>"
headers = {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
}
cookies = {
    "outpost_console": "<console-session>",
}

response = requests.delete(url, headers=headers, cookies=cookies, timeout=30)
response.raise_for_status()
print(response.json())

Go

// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.
package main

import (
  "fmt"
  "io"
  "log"
  "net/http"
)

func main() {
  req, err := http.NewRequest(http.MethodDelete, "https://depot.example.com/api/v1/vault/shares/<shareId>", nil)
  if err != nil {
    log.Fatal(err)
  }

  req.Header.Set("X-CSRF-Token", "<csrf-token>")
  req.Header.Set("Accept", "application/json")
  req.AddCookie(&http.Cookie{Name: "outpost_console", Value: "<console-session>"})

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()

  out, err := io.ReadAll(resp.Body)
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(resp.Status, string(out))
}

TypeScript

// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.
// The session cookie is set by signing in. A script cannot set it itself.

const url = "https://depot.example.com/api/v1/vault/shares/<shareId>";

const response = await fetch(url, {
  method: "DELETE",
  headers: {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
  },
  credentials: "include",
});

if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);

C#

// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.

using System;
using System.Net.Http;

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Delete, "https://depot.example.com/api/v1/vault/shares/<shareId>");
request.Headers.TryAddWithoutValidation("X-CSRF-Token", "<csrf-token>");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("Cookie", "outpost_console=<console-session>");

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());