Getting Started

Updated 2025-04-29

İpucu

Test and explore the API endpoints with our interactive Postman Collection.

Base URI

https://REGION.onetimesecret.com/api

Where REGION is one of ca, eu, nz, uk, or us.

Data Locality and Region Selection

• Choose a region (e.g. EU eu.onetimesecret.com, UK uk.onetimesecret.com, or US us.onetimesecret.com). See Regions for all options.
• 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:APITOKEN@REGION.onetimesecret.com/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:

• CA Data Center: ca.onetimesecret.com
• EU Data Center: eu.onetimesecret.com
• NZ Data Center: nz.onetimesecret.com
• UK Data Center: uk.onetimesecret.com
• US Data Center: us.onetimesecret.com

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 our 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://uk.onetimesecret.com/api/v1/status
{"status":"nominal"}

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