Create External

CreateExternal creates a secret vault for external email recipients.

POST /api/v1/secrets/external

CreateExternal

Go

package main

import(
	"context"
	"github.com/conductorone/conductorone-sdk-go/pkg/models/shared"
	conductoronesdkgo "github.com/conductorone/conductorone-sdk-go"
	"log"
)

func main() {
    ctx := context.Background()

    s := conductoronesdkgo.New(
        conductoronesdkgo.WithSecurity(shared.Security{
            BearerAuth: "<YOUR_BEARER_TOKEN_HERE>",
            Oauth: "<YOUR_OAUTH_HERE>",
        }),
    )

    res, err := s.PaperSecret.CreateExternal(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }
    if res.PaperSecretServiceCreateResponse != nil {
        // handle response
    }
}

200

{
  "ageRecipient": "<string>",
  "secret": {
    "allowedEmails": [
      "<string>"
    ],
    "allowedUserIds": [
      "<string>"
    ],
    "contentDeleted": true,
    "contentExpiresAt": "2023-11-07T05:31:56Z",
    "contentReady": true,
    "contentType": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "creatorUserId": "<string>",
    "currentViews": 123,
    "deletedAt": "2023-11-07T05:31:56Z",
    "displayName": "<string>",
    "fileSize": "<string>",
    "filename": "<string>",
    "inputFormat": "SECRET_INPUT_FORMAT_UNSPECIFIED",
    "maxViews": 123,
    "secretType": "SECRET_TYPE_UNSPECIFIED",
    "shareCode": "<string>",
    "shareUrl": "<string>",
    "sharingMode": "PAPER_VAULT_SHARING_MODE_UNSPECIFIED",
    "status": "SECRET_STATUS_UNSPECIFIED",
    "updatedAt": "2023-11-07T05:31:56Z",
    "vaultId": "<string>"
  },
  "uploadUrl": "<string>",
  "vaultId": "<string>"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Authorization · string · header · required

This API uses OAuth2 with the Client Credential flow. Client Credentials must be sent in the BODY, not the headers. For an example of how to implement this, refer to the c1TokenSource.Token() function.

Body

application/json

The PaperSecretServiceCreateExternalRequest message.

allowedEmails · string[] | null

External email addresses allowed to view this secret (1 to 64). Recipients authenticate via email magic link or Google OAuth.

contentType · string

For FILE secrets: MIME content type of the original file. Ignored for TEXT secrets.

displayName · string

Optional cleartext label visible to the creator in "My Secrets" view. Not encrypted — do not put sensitive data here.

expiresIn · string<duration>

fileSize · string<int64>

For FILE secrets: expected file size in bytes (max 1GB). Ignored for TEXT secrets.

filename · string

For FILE secrets: original filename (sanitized server-side). Ignored for TEXT secrets.

inputFormat · enum<string>

For TEXT secrets: hint about the plaintext format (e.g., JSON, YAML, key-value). Used by the viewer UI for syntax highlighting. Does not affect encryption.

Available options: SECRET_INPUT_FORMAT_UNSPECIFIED, SECRET_INPUT_FORMAT_PLAINTEXT, SECRET_INPUT_FORMAT_JSON, SECRET_INPUT_FORMAT_YAML, SECRET_INPUT_FORMAT_KEY_VALUE

maxViews · integer<uint32>

Maximum number of views before the secret is burned (0 = unlimited).

secretType · enum<string>

Secret type: TEXT or FILE. TEXT secrets use SetTextContent to upload encrypted content (max 64KB). FILE secrets use the upload_url from CreateResponse to upload encrypted content (max 1GB).

Available options: SECRET_TYPE_UNSPECIFIED, SECRET_TYPE_TEXT, SECRET_TYPE_FILE

Response

200 - application/json

Successful response

The PaperSecretServiceCreateResponse message.

ageRecipient · string

Age X25519 recipient public key (format: "age1...") for client-side encryption. All content MUST be encrypted to this recipient using the Age encryption format before calling SetTextContent or uploading to upload_url. See: https://age-encryption.org

secret · Paper Secret · object

PaperSecret is the API view of a secret (combines Vault + PaperVault fields). The vault_id is the primary identifier (Vault.id).

Show child attributes

uploadUrl · string

For FILE secrets: capability URL for uploading the Age-encrypted file. Send an HTTP PUT request with the Age-encrypted file bytes as the body and Content-Type: application/octet-stream. The payload MUST begin with the Age header "age-encryption.org/v1\n". Maximum file size: 1GB. Empty for TEXT secrets.

vaultId · string

Vault ID - primary identifier for this secret.