Onetime SecretOnetime SecretDocs
REST API

Getting Started

Onetime Secret's REST API provides flexible secret sharing capabilities, supporting both authenticated and anonymous usage. Authenticated users gain advanced features and higher usage limits, while unauthenticated users can quickly share secrets with basic functionality.

Updated 2024-11-06

All API access is over HTTPS and all responses are JSON.

Base URI

https://REGION.onetimesecret.com/api

Where REGION is either us or eu.

Data Locality and Region Selection
  • Choose between US (us.onetimesecret.com) or EU (eu.onetimesecret.com) data centers
  • Consider factors like data sovereignty, latency, and compliance requirements
  • NOTE: Default onetimesecret.com remains operational and routes to an active data center, using a specific locality is recommended as this functionality may be deprecated in the future.

Authentication

We support two modes of API usage:

Authenticated Access

https://USERNAME:[email protected]/api

  • Use HTTP Basic Authentication for full API capabilities
  • The username is your account login
  • The password is the API token from your account page

Anonymous Access

https://REGION.onetimesecret.com/api

  • Limited functionality available without authentication
  • Ideal for quick, one-time secret sharing
  • Can be used for both creating and retrieving secrets

Data Locality

Onetime Secret supports multiple geographic data centers. We follow a zero data sharing policy between regions, ensuring complete data isolation. Choose the right data center for your needs:

Important Considerations:

  • You can choose a specific data locality by navigating directly to the desired domain
  • The location of your secret is always clear from the generated link (e.g., us.onetimesecret.com/secret/abcd1234)
  • NOTE: Currently, access via onetimesecret.com/api is still operational but using a specific locality is recommended as this functionality may be deprecated in the future.

Custom Domains

Onetime Secret supports custom domain configurations for organizations with specific networking or branding requirements via out Identity Plus plan.

Custom Domain Benefits

  • Private Branding: Use your own domain (e.g., secrets.example.com) for API access and secret sharing
  • Consistent User Experience: Maintain your organization's visual and trust identity with your customers and partners.
  • Include during employee training: Use custom domains to reinforce your organization's security practices and workflows.
Premium Feature Custom domains are available on our Identity Plus plan. Setup in minutes with our easy-to-use configuration options. Learn more.

API Usage with Custom Domains

When using a custom domain, all API endpoints follow the same structure:

https://secrets.example.com/api

System Status

GET https://REGION.onetimesecret.com/api/v1/status Current status of the system.

Parameters: None

$ curl -u 'USERNAME:APITOKEN' https://eu.onetimesecret.com/api/v1/status
{"status":"nominal"}

$ curl -u 'USERNAME:APITOKEN' https://us.onetimesecret.com/api/v1/status
{"status":"nominal"}

Data Center Regions

Learn about Onetime Secret's data center regions and how to choose the right one for your needs.

Creating Secrets

Learn how to create and retrieve secrets using the Onetime Secret REST API, with support for both authenticated and anonymous usage.