Authentication

The API requires a personal access token on every request. Tokens are free and tied to your timezone.io account.

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.

Authenticate a request

Send the token in the Authorization header as a bearer token:

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

That's the only credential you need. There are no separate scopes — a token can read every endpoint in v1.

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": "..." }

Keep tokens secret. Treat them like passwords: never commit them to source control or expose them in client-side code. Revoke any token from the API tokens page if it leaks.