en-US/about_OnetimeSecretV2.help.txt
|
TOPIC about_OnetimeSecretV2 SHORT DESCRIPTION The official PowerShell module for the Onetime Secret API. LONG DESCRIPTION Onetime Secret (https://onetimesecret.com) shares sensitive information through links that can be viewed exactly once, after which the secret is permanently deleted. This module wraps the v2 REST API so you can create, inspect, reveal and burn secrets from scripts and the command line. Vocabulary Secret The content being shared and the link the recipient opens. Identified by a SecretId (the key in the share link). Receipt The creator's record of a secret: its state, timing, memo, and the share/receipt/burn links. Identified by a ReceiptId. Keep the receipt; it is how you check on a secret or burn it early. Burn Destroy an unread secret before its expiry, using its receipt. Cmdlets Connect-OtsAccount Set the server (region) and credential to use. Disconnect-OtsAccount Forget the default connection. Get-OtsConnection Show the connection in use. New-OtsSecret Conceal a value, or generate a random one. Get-OtsSecret Read a secret's metadata without revealing it. Get-OtsSecretStatus Cheap existence/state check, several at once. Receive-OtsSecret Reveal a secret (consumes it). Get-OtsReceipt Show one receipt, or list the last 30 days. Set-OtsReceipt Set a receipt's memo. Remove-OtsSecret Burn a secret via its receipt. Get-OtsStatus Service health for a server. Get-OtsVersion Server build version (needs a credential). Get-OtsSupportedLocale Locales a server can serve. Connecting Onetime Secret runs region-isolated deployments, so there is no default server. Choose your region's host, your self-hosted instance or your custom domain: Connect-OtsAccount -ServerUri https://eu.onetimesecret.com ` -Credential (Get-Credential -UserName ur1abc23def) The credential's username is your customer extid (the "ur..." identifier at the bottom of the user menu when signed in) or your account email; the password is your API token. Add -Anonymous to use the guest endpoints without an account. Environment variables are honoured when no connection has been made: ONETIME_BASE_URL https://eu.onetimesecret.com ONETIME_CUSTOMER_EXTID ur1abc23def ONETIME_API_TOKEN your API token Errors Failed API calls raise terminating errors with: FullyQualifiedErrorId OnetimeSecret.Api.<error_type>, e.g. OnetimeSecret.Api.RecordNotFound CategoryInfo mapped from the HTTP status (ObjectNotFound, AuthenticationError, LimitsExceeded, ...) Exception.Data StatusCode, ErrorType, Field, ErrorId, RequestId, Method, Uri, Response Example: try { Receive-OtsSecret abc123 } catch { if ($_.Exception.Data['StatusCode'] -eq 404) { 'already gone' } else { throw } } Pipelines Objects carry ReceiptId and SecretId as properties, and every cmdlet that takes an identifier binds it from the pipeline by property name, so receipts and secrets flow between cmdlets: New-OtsSecret -Generate | Set-OtsReceipt -Memo 'temp pw' -PassThru Get-OtsReceipt | Where-Object State -eq new | Remove-OtsSecret Get-OtsReceipt | Get-OtsSecretStatus Identifiers may be given as bare keys or as the full links. SEE ALSO https://api.onetimesecret.com/doc/api-v2 https://gitlab.com/onetimesecret/onetimesecret-powershell |