Authentication

Every request needs a personal access token sent as a bearer token. Tokens are free and tied to your timezone.io account:

curl https://api.timezone.io/v1/timezones \
  -H "Authorization: Bearer YOUR_API_TOKEN"

That is the only credential there is — no separate scopes, no OAuth dance. A token can read every endpoint in v1.

Get a token

  1. Create a free account and verify your email address. Email verification is required — unverified accounts cannot call the API.
  2. Open API tokens in your settings.
  3. Name your token (e.g. production or cli) and create it.
  4. Copy the token immediately. It is shown once and stored hashed — if you lose it, revoke it and create a new one.

Failed authentication

Status When Body
401 The token is missing, malformed, or revoked. { "message": "Unauthenticated." }
403 The token is valid but the account's email isn't verified. { "message": "Your email address is not verified." }

Keep tokens secret

Treat a token like a password:

  • Load it from an environment variable or secret store — never commit it to source control.
  • Never expose it in client-side code; browsers ship your bundle to everyone. Proxy API calls through your backend instead.
  • Use one token per environment or integration (production, staging, cli) so a leak can be revoked without taking everything down.
  • Revoke a leaked token from the API tokens page — revocation is immediate.