API ReferenceSecret References

Create a secret reference

Requires a mode-B access proxy configured for the organization (a proxy public key). Without it, encryption cannot be performed and the request returns 422.

name is the only identifier: it must be unique per namespace (a deleted reference frees its name for reuse). vaultKey is the vault lookup key/path; it is encrypted and never returned.

Authentication

AuthorizationBearer

WorkOS organization API key (Authorization: Bearer sk_…).

Path parameters

namespaceIdstringRequiredformat: "uuid"

Headers

Idempotency-KeystringOptional

Optional idempotency key; a replay within the retention window returns the stored response.

Request

This endpoint expects an object.
namestringRequired
Unique per namespace.
vaultTypestringRequired
vaultKeystringRequired

Vault lookup key/path. Encrypted server-side; never returned.

metadatamap from strings to anyOptional
Arbitrary JSON object, or null.

Response

Created
dataobject

The secret’s vaultKey is encrypted server-side and never returned. name is the only identifier.

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error