8 min read
Unix timestamp explained
Unix timestamps count time from the Unix epoch, but seconds, milliseconds, and timezones often cause confusion.
Table of contents
The Unix epoch
Unix time counts elapsed time from January 1, 1970 at midnight UTC. A timestamp is just a number, which makes it compact and easy for systems to compare. It is not naturally friendly for humans to read.
Because the count is based on UTC, the same timestamp represents the same instant everywhere. Local timezone only affects how that instant is displayed.
Seconds vs milliseconds
The most common timestamp bug is mixing seconds and milliseconds. A 10-digit value is usually seconds. A 13-digit value is usually milliseconds. JavaScript Date expects milliseconds, while many APIs and JWT claims use seconds.
If a converted date appears thousands of years in the future or near 1970, check the unit first. Multiplying or dividing by 1000 may be the missing step.
JWTs, logs, and APIs
JWT claims such as exp, iat, and nbf use Unix seconds. Logs may use seconds, milliseconds, microseconds, or ISO strings depending on the platform. API payloads should document the expected unit to avoid client confusion.
When debugging, convert the value to UTC and local time. UTC helps compare systems, while local time helps humans reason about what happened in their timezone.
Best practices
Store and transmit timestamps consistently. Use UTC for server-side data and include clear units in field names or documentation. For display, format the timestamp at the edge of the application where the user's locale is known.
When writing tests, use fixed timestamps instead of current time when possible. Stable values make snapshots and fixtures easier to review.
Related guides
What is JWT and how to decode it
JWTs are common in authentication. Learn what the three sections mean and why decoding is not verification.
Best practices for working with API responses
API responses are easier to debug when you validate syntax, format payloads, inspect errors, and compare changes deliberately.
What is Base64 encoding
Base64 turns bytes into text-safe characters for transport, but it is reversible and should not be treated as security.
FAQ
What is the Unix epoch?
The Unix epoch is January 1, 1970 at 00:00:00 UTC.
Are Unix timestamps seconds or milliseconds?
Classic Unix timestamps use seconds, while JavaScript Date values use milliseconds.
Do timestamps include timezone?
A Unix timestamp represents an instant in UTC; timezone is applied when displaying it.
Why do JWT timestamps look short?
JWT exp, iat, and nbf claims use seconds since the Unix epoch.