Getting Started
Updated 2024-11-06
All API access is over HTTPS and all responses are JSON.
Base URI
Section titled “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.comremains operational and routes to an active data center, using a specific locality is recommended as this functionality may be deprecated in the future. ::
Authentication
Section titled “Authentication”We support two modes of API usage:
Authenticated Access
Section titled “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
Section titled “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
Section titled “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:
- EU Data Center: eu.onetimesecret.com
- US Data Center: us.onetimesecret.com
Important Considerations:
Section titled “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/apiis still operational but using a specific locality is recommended as this functionality may be deprecated in the future.
Custom Domains
Section titled “Custom Domains”Onetime Secret supports custom domain configurations for organizations with specific networking or branding requirements via our Identity Plus plan.
Custom Domain Benefits
Section titled “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
Section titled “API Usage with Custom Domains”When using a custom domain, all API endpoints follow the same structure:
https://secrets.example.com/api
System Status
Section titled “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"}