Authentication

API Key Authentication

All API requests (except /health) require authentication via a Bearer token in the Authorization header:

Authorization: Bearer osm_live_aBcDeFgHiJkLmNoPqRsT...

Getting your API key

1. Register at app.oneshotemail.com (or via POST /account/register).
2. Your API key is displayed exactly once on registration. Copy it immediately.
3. Store it securely — in a password manager, CI/CD secrets, or your OS keychain.

API key format

OneShotMail API keys follow a consistent format:

osm_live_<random_characters>

• osm_ — Identifies this as a OneShotMail key.
• live_ — Indicates a production key.
• The rest is a cryptographically random string.

The osm_live_ prefix makes it easy to identify OneShotMail keys in your codebase and set up secret scanning rules.

Setting the API key

Environment variable (recommended)

All SDKs and the CLI read the ONESHOT_API_KEY environment variable by default:

export ONESHOT_API_KEY="osm_live_your_key_here"

This is the recommended approach for CI/CD pipelines and local development:

# GitHub Actions
env:
  ONESHOT_API_KEY: ${{ secrets.ONESHOT_API_KEY }}

Direct configuration

Every SDK also accepts the API key as a constructor argument:

# Python
client = oneshot.Client(api_key="osm_live_your_key_here")

// Go
client := oneshot.NewClient("osm_live_your_key_here")

# Ruby
client = OneShot::Client.new(api_key: "osm_live_your_key_here")

// JavaScript / TypeScript
const client = new OneShotClient("osm_live_your_key_here");

// Java
var client = new OneShotClient("osm_live_your_key_here");

CLI configuration

# Set via the config command
oneshot config set api-key osm_live_your_key_here

# Or use the environment variable
export ONESHOT_API_KEY="osm_live_your_key_here"

The CLI checks for the API key in this order:

1. ONESHOT_API_KEY environment variable
2. Config file at ~/.config/oneshot/config.toml

curl example

curl -H "Authorization: Bearer osm_live_your_key_here" \
  https://api.oneshotemail.com/v1/account

Authentication errors

If the API key is missing, invalid, or revoked, the API returns a 401 Unauthorized response:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key."
  }
}

Security best practices

• Never commit API keys to source control. Use environment variables or a secrets manager.
• Rotate keys if compromised. Regenerate your key from the account settings page. The old key is immediately invalidated.
• Use CI/CD secrets. Store your API key in GitHub Actions secrets, GitLab CI variables, or your CI platform’s secrets store.
• One key per environment. Use separate accounts (and keys) for development, staging, and production testing if you need environment isolation.

Rate limiting

API requests are rate-limited per API key based on your plan:

Plan	Rate limit
Free	5 rps
Solo	50 rps
Team	200 rps
Enterprise	500 rps
Max	1,000 rps

When rate-limited, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 2 seconds."
  }
}

All SDKs expose the Retry-After value in the RateLimitedError exception so you can implement appropriate backoff.

Base URL

The API base URL is:

https://api.oneshotemail.com/v1

All SDKs default to this URL. You can override it for local development or testing:

# Point to a local development server
client = oneshot.Client(
    api_key="test_key",
    base_url="http://localhost:4566/v1"
)

The ONESHOT_BASE_URL environment variable is also supported by the Python SDK.