DEV Community: Julian Halden

WebAuthn RP ID vs Origin: Fixing Cross-Domain Passkeys

Julian Halden — Sat, 24 Oct 2026 04:42:24 +0000

If your passkey works on one hostname but fails on another, start by comparing the RP ID with the actual calling origin.

They are not interchangeable values. An RP ID is a domain identifier. An origin includes the scheme, hostname, and port.

This is part three of Passkeys in Production, adapted from the Helpers.work RP ID guide. We build the Passkey Deployment Checker, which evaluates this public configuration boundary without claiming to test the entire login flow.

One URL, three different values

For this illustrative page:

https://login.example.com/account/security

You have:

Origin:   https://login.example.com
Hostname: login.example.com
RP ID:    potentially example.com or login.example.com

The path is not part of the origin. A non-default port is part of the origin, but never part of the RP ID.

Registration options use publicKey.rp.id; authentication options use publicKey.rpId. The server's expected RP ID must agree with the credential's scope.

The ordinary relationship is directional

Without Related Origin Requests, a caller can use its own effective domain or an eligible parent domain as the RP ID.

Caller	RP ID	Ordinary relationship
`https://login.example.com`	`example.com`	Eligible parent
`https://login.example.com`	`login.example.com`	Same host
`https://example.com`	`login.example.com`	Not an eligible parent
`https://shop.example.com`	`login.example.com`	Sibling, not parent
`https://example.co.uk`	`example.com`	Different domain

A public suffix such as com or co.uk is not an acceptable shared RP ID.

This is why "just remove the first subdomain" is not a sufficient validation algorithm. Public suffix handling needs standards-aware logic.

Sibling subdomains do not always need a JSON file

If accounts.example.com and shop.example.com both use credentials registered for example.com, the ordinary relationship can be enough.

You still need:

Credentials created for that exact RP ID.
Correct shared account and credential mappings.
Explicit server acceptance of the intended origins.

A broad RP ID does not authorize every subdomain in your backend. Treat delegated, abandoned, and user-controlled subdomains as part of the threat model.

Cookies and shared sessions remain separate concerns.

Different domains need explicit authorization

Suppose the browser runs at https://example.co.uk but requests RP ID example.com.

A supporting browser can use Related Origin Requests if the RP ID domain publishes:

https://example.com/.well-known/webauthn

For example:

{
  "origins": ["https://example.co.uk", "https://login.example.net"]
}

These are illustrative origins. Serve your actual document publicly as JSON and list only relationships you intend to trust.

The location matters: putting this file on example.co.uk does not authorize use of the example.com RP ID.

The server still verifies the actual origin

The public allowlist permits the browser to request the credential. It does not replace the relying party's verification policy.

For the example above, the server must explicitly accept https://example.co.uk, verify the expected challenge and RP ID context, and validate the appropriate cryptographic response.

Do not fix a mismatch by accepting arbitrary origins. CORS headers and cookie-domain changes also do not substitute for WebAuthn authorization.

Five labels is not five URLs

The compatibility procedure counts registrable domain labels:

example.com contributes example.
example.co.uk also contributes example.
login.example.net also contributes example.
example-rewards.com contributes example-rewards.

Supporting implementations must handle at least five distinct labels; they may support more. The checker evaluates that five-label baseline.

Order matters when a client exhausts its label budget. A listed origin can still fall beyond the supported limit.

Do not publish a giant list and assume every client will process all of it. For many unrelated tenant domains, a central sign-in domain may be the more maintainable design.

Debug in this order

First, inspect the actual origin where WebAuthn runs. A redirect from a marketing page can change the relevant hostname.

Second, inspect the backend-generated options. Do not assume the RP ID was discovered by a scanner; the Helpers.work tool defaults to the hostname when the RP ID is omitted.

Third, determine whether ordinary parent-domain eligibility is enough. If not, inspect the RP ID host:

curl --proto '=https' --max-time 15 --silent --show-error --include \
  https://example.com/.well-known/webauthn

Replace the example domain with yours. Look for HTML fallbacks, login challenges, incorrect content types, or missing origins.

Finally, test browser support and server verification. Basic WebAuthn support does not guarantee Related Origin Requests support. A SecurityError is a diagnostic clue, not a complete root-cause report.

Domain changes are credential migrations

Existing credentials do not change RP ID when you update configuration.

Before renaming an authentication domain, decide whether to retain the old RP ID through a supported related-origin flow or guide users through authenticated re-enrollment. Keep a tested path for unsupported clients.

Continue with reading the checker report. For the broader rollout, see the deployment checklist and passkeys overview.

References: W3C related origins and web.dev's implementation guide.

A Passkey Deployment Checklist Beyond the Happy-Path Demo

Julian Halden — Sat, 24 Oct 2026 04:42:16 +0000

Creating a passkey once on your laptop is not the same as deploying passkeys.

A production release needs evidence at three layers: public configuration, server verification, and the real user journey. A failure at any layer can produce a broken experience even when the other two look healthy.

This is part two of Passkeys in Production, adapted from our full deployment checklist. Helpers.work also provides the Passkey Deployment Checker used for the public-configuration layer.

1. Record the identity boundary

Write down the actual sign-in origin, RP ID, allowed server origins, credential store, and native app identifiers.

An illustrative setup:

Sign-in origin: https://login.example.com
RP ID:          example.com
Server policy:  explicitly allow https://login.example.com

The RP ID is not necessarily the hostname visible in the address bar. Read it from the options your backend produces.

Keep staging and production boundaries intentional. A parent-domain RP ID combined with overly broad server origin acceptance can expose production authentication to weaker environments.

2. Check public HTTPS

Verify the real login hostname, not only the marketing site:

DNS resolves to the intended service.
The certificate covers that hostname.
The server sends a complete chain.
HTTPS redirects stay on HTTPS.
Renewal and expiry monitoring are working.

The SSL Certificate Checker can help identify certificate problems. A valid certificate on the apex domain is not proof that every login subdomain is configured correctly.

Localhost development exceptions do not make HTTP production suitable. A public checker also should not be used to scan private infrastructure.

3. Publish only the files you need

Deployment feature	Relevant configuration
Ordinary single-domain web sign-in	HTTPS, eligible RP ID, server verification
Cross-domain use of one RP ID	`/.well-known/webauthn`
Credential-manager discovery	Optional `/.well-known/passkey-endpoints`
Native Apple app	Associated Domains and `webcredentials`
Native Android app	Digital Asset Links and release signing identity

Sibling subdomains using an eligible common parent RP ID do not normally need Related Origin Requests. They still need explicit server origin validation.

4. Inspect the deployed response

A reverse proxy can turn a well-known request into a redirect or an HTML application shell. Inspect status, headers, and body together:

curl --proto '=https' --max-time 15 --silent --show-error --include \
  https://example.com/.well-known/passkey-endpoints

Replace the example domain with your RP ID. This command leaves redirects visible instead of following them.

An illustrative discovery document:

{
  "enroll": "https://example.com/account/passkeys/new",
  "manage": "https://example.com/account/passkeys"
}

The JSON should be publicly retrievable. The account pages themselves can require authentication and must enforce your enrollment policy.

These are user-facing discovery links, not WebAuthn verification APIs. An absent passkey-endpoints document does not by itself break sign-in.

5. Verify mobile release identity

For Apple, the public association file and the app's entitlement must agree. Check webcredentials, not just applinks, and preserve existing association sections.

For Android, compare the package name and signing-certificate fingerprint for the build users actually install. A debug certificate or upload certificate can differ from the distribution certificate.

The credential-sharing relation is delegate_permission/common.get_login_creds. Follow the Android prerequisites for the surrounding configuration.

A public file scanner cannot inspect your installed binary or force platform association caches to refresh. Test the distributed app.

6. Exercise the backend rejection paths

Use a maintained verifier, then test your own wiring:

Unexpected, expired, and replayed challenges are rejected.
Unapproved origins are rejected.
The RP ID context must match.
Required presence and verification flags are enforced.
A credential cannot authenticate a different account.
Revoked credentials cannot start a new session.

Challenges should be bound to the intended operation and consumed reliably. Do not allow concurrent requests to make a completed challenge reusable.

Be careful with signature counters. Some authenticators and synced credentials do not supply a useful monotonic counter. Apply the library's documented policy rather than treating every non-increase as definitive evidence of cloning.

7. Test the lifecycle

First enrollment is only the start. Test sign-out, sign-in, prompt cancellation, second-credential enrollment, revocation, device loss, and recovery.

Include the browsers, operating systems, credential providers, and mobile builds your audience actually uses. Conditional UI and related-origin support can differ from basic WebAuthn support.

Keep fallback explicit. An unsupported client should not trigger a hidden bypass of origin or verification policy.

8. Plan rollback without locking users out

Stopping new enrollments and stopping existing passkey authentication are different changes. During an incident, the second can strand users who no longer have another sign-in method.

Preserve credential records and the RP ID through an ordinary frontend rollback. Test recovery before removing passwords, and decide which recovered sessions may immediately enroll a new credential.

Track aggregate completion and failure categories without collecting raw credential payloads as routine analytics.

The release gate

Run the Passkey Deployment Checker with your actual RP ID and expected app values. Then complete server and real-device tests.

No public scan can prove your challenge storage, account mapping, session issuance, or recovery process is correct.

Continue with RP ID and related origins, or use the report interpretation guide. New to the model? Start with passkeys explained.

References: W3C WebAuthn, passkey endpoints, and Apple associated domains.

Passkeys Explained: What Changes Behind the Sign-In Button

Julian Halden — Sat, 24 Oct 2026 04:42:07 +0000

A passkey is not your fingerprint stored on a website. It is a public-key credential, and the fingerprint prompt is one possible way to authorize its use locally.

That distinction explains both the appeal of passkeys and the engineering work that remains after adding a sign-in button.

This is part one of Passkeys in Production, adapted from the Helpers.work passkeys guide. We build the Passkey Deployment Checker, so this series also explains what a public configuration check can and cannot establish.

The smallest useful mental model

With a password, the user presents a reusable secret. With a passkey, an authenticator answers a fresh challenge using a private key, and your server verifies the response using a public key.

Your server:       challenge + authentication options
Browser:          asks the authenticator for a credential
Authenticator:    user approval + signed response
Your server:       verification + application session

The website never needs the private key. It does need a reliable mapping between credential IDs, public keys, and accounts.

Registration creates that mapping. Authentication uses it. Do not treat registration as a harmless settings change: enrolling a new credential gives someone a new way to enter the account.

What WebAuthn does

On the web, WebAuthn exposes credential creation and authentication through the browser. The browser and authenticator enforce the credential's relying party scope.

The RP ID is a domain identifier, such as example.com. It is not the same as the browser origin, such as https://login.example.com.

Your backend must verify the challenge, expected origin, RP ID context, applicable user-presence and user-verification requirements, and the appropriate cryptographic response. For authentication, that includes the assertion signature against the correct stored public key.

A signature-only implementation is incomplete. Use a maintained WebAuthn server library and test your configuration around it.

Why this is harder to phish

A lookalike domain cannot normally request credentials for your RP ID. The person does not have to inspect a convincing login page and decide where to type a reusable secret.

That is a different property from a one-time code. Someone can copy an OTP into a phishing page. A correctly scoped credential is not a code that can be pasted anywhere.

There are deliberate cross-domain mechanisms, including Related Origin Requests. They need explicit configuration, not a permissive origin wildcard.

Phishing resistance is not total account security. A stolen session, a compromised server, unsafe credential enrollment, and weak recovery can still put an account at risk.

Synced does not mean universal

Some passkeys synchronize through a credential provider. Others are bound to an authenticator, such as a hardware security key.

These models produce different support questions:

Credential model	Question to test
Synced	Is the credential available through the user's chosen provider on the next device?
Device-bound	What happens if the authenticator is lost or damaged?
Cross-device authentication	Can the user complete the intended approval flow from another device?

A QR-code flow does not necessarily copy a passkey to the computer. It may let another device perform authentication.

Likewise, "supports passkeys" does not promise the same autofill or cross-device experience in every browser.

Is a passkey automatically MFA?

Not every WebAuthn operation has the same assurance properties. Local user verification can combine an authenticator with a PIN or biometric check, but a touch-only interaction has different semantics.

Specify the policy you need, request the appropriate verification behavior, and verify it on the server. Do not assume that the presence of a security-key prompt satisfies every organizational MFA requirement.

The website receives a cryptographic response, not a fingerprint image. That is an important privacy distinction to explain in onboarding copy.

The part the demo usually leaves out

Before rolling out, test more than first registration:

Sign out and authenticate with a fresh challenge.
Cancel the prompt and recover gracefully.
Add a second credential.
Remove a credential and reject its future use.
Recover after losing the only available authenticator.
Try an unsupported browser or device.

The resulting session needs the same care as any other authenticated session. Passkeys do not fix authorization bugs or unsafe cookies.

Use user-facing labels such as "Create a passkey" instead of "Scan your fingerprint." A user's actual authenticator may use a PIN, face recognition, or a security key.

You do not need every well-known file

A web-only deployment with an eligible RP ID can work without native app association files.

Related origins matter when different domains need one RP ID. Apple and Android association files matter for the relevant native apps. Passkey endpoints are optional metadata that helps clients discover enrollment and management pages.

The Passkey Deployment Checker inspects public configuration. It cannot register a credential for your account, audit your backend verifier, or prove recovery works. A clean report is one piece of evidence, not the final release gate.

Continue the series

For the underlying API and verification requirements, see MDN's Web Authentication overview and the W3C WebAuthn specification.

How to Read a Passkey Deployment Checker Report

Julian Halden — Sat, 24 Oct 2026 04:41:56 +0000

A website can have valid passkey metadata and a broken authentication flow. It can also support passkeys while publishing none of the optional discovery files a scanner looks for.

The useful question is not "How many green checks do I have?" It is "Which conditions did this report evaluate, and which of them does my architecture require?"

This is the final part of Passkeys in Production, adapted from the full report guide. We build the Helpers.work Passkey Deployment Checker; this walkthrough describes its actual scope.

Use the origin where WebAuthn runs

Enter your public sign-in URL or domain. The tool normalizes it to an origin, so supplying /account/security does not turn the scan into a test of that page.

If the marketing site redirects to a login host, use the host where the browser actually creates or requests credentials.

The checker uses public HTTPS domains on port 443. It does not scan localhost, IP-literal targets, private networks, custom website ports, or URLs containing embedded credentials.

Those are tool restrictions. They are not a claim that every excluded environment is inherently unsupported by WebAuthn.

Enter your real RP ID

The most important advanced field is the RP ID.

Website: https://login.example.com
RP ID:   example.com

This illustrative setup may be intentional. If you omit the RP ID, the tool instead uses login.example.com and marks the source as inferred.

That is a default, not reliable discovery. Read publicKey.rp.id in registration options and publicKey.rpId in authentication options from your backend.

See the RP ID guide if the domain relationship is unclear.

Know the six checks

Check	What it evaluates
HTTPS Configuration	Public connectivity and normal certificate validation
RP ID Compatibility	Website-to-RP relationship for the supplied inputs
Related Origins	RP-host `/.well-known/webauthn` and applicable origins
Passkey Endpoints	Optional discovery metadata and URL syntax
Apple App Site Association	Public `webcredentials` declarations
Android Asset Links	Public credential-sharing statements and expected identity

HTTPS and RP ID checks are always evaluated. Related origins and passkey endpoints are selected by default; mobile checks are opt-in.

An unrelated RP ID forces the required related-origin evaluation even if the optional selection is off.

For native apps, provide expected identifiers and the actual release signing-certificate fingerprint when available. Without expected values, valid JSON for another app is not proof that your app is configured.

Read statuses instead of inventing a score

Status	Meaning
`passed`	The evaluated condition passed for these inputs
`warning`	A concern or compatibility limitation needs review
`failed`	The evaluated condition failed
`not_applicable`	Not selected, or optional configuration is not applicable
`unknown`	The checker could not reach a reliable conclusion

The report-level success value means a report was produced. It does not mean all checks passed.

A required related-origin failure can block your intended cross-domain flow. A missing optional discovery document may not affect sign-in at all. A network timeout should not be relabeled as either a pass or a confirmed deployment defect.

Three examples of useful interpretation

These are hypothetical scenarios, not live scan results.

The web-only application

The site uses an eligible RP ID and has no native apps. Apple and Android association files are not relevant to that deployment.

A missing /.well-known/passkey-endpoints file is also not proof that passkeys are unavailable. It is optional metadata for helping clients find enrollment and management pages.

Focus on the actual registration and authentication ceremony.

The cross-domain application

The browser runs at https://example.co.uk and requests RP ID example.com.

Inspect https://example.com/.well-known/webauthn. Verify the calling origin is represented, the body is usable JSON, and the client supports the mechanism.

The backend still needs explicit origin acceptance and the correct credential records.

The Android release-only failure

The public file may contain a debug or upload-certificate fingerprint rather than the certificate on the distributed app.

Compare package name, credential-sharing relation, and release signing identity together. The scanner cannot inspect the installed binary or app manifest.

Some green results have important limits

A passkey-endpoints result validates advertised URLs syntactically. It does not visit those URLs or exercise enrollment.

An Apple association result does not verify the app entitlement or Apple's cached state. An Android result does not verify the manifest, resources, or installed signing certificate.

An HTTPS result is not a full TLS audit. It does not evaluate every cipher, security header, or route.

And no public configuration report verifies challenge freshness, assertion signatures, account mapping, session issuance, or account recovery.

Fix the failed layer, then test again

Work from DNS and HTTPS toward RP ID, required files, clients, and the server ceremony.

An HTML response with status 200 often points to a catch-all route, not malformed JSON. Redirect handling also differs: this checker follows bounded HTTPS redirects for related origins but treats passkey-endpoint and app-association redirects differently.

After deployment, inspect the public response rather than assuming the local file is already visible through the CDN.

Then register, sign out, sign in, cancel, revoke, and recover on your supported clients. Use the production checklist as the final release gate.

For the conceptual foundation, see passkeys explained. Technical references: W3C passkey endpoints, Apple associated domains, and Android prerequisites.

Unix Timestamps Explained: Seconds, Milliseconds, Time Zones and Common Mistakes

Julian Halden — Fri, 25 Sep 2026 23:56:59 +0000

Unix timestamps are everywhere. APIs, databases, logs, JavaScript and authentication tokens all use them, and they cause a surprising number of bugs.

Is 1790186400 a date? What about 1790186400000? Does a Unix timestamp contain a time zone? Why does JavaScript sometimes show a date in your local time when the timestamp itself is supposed to be UTC?

This article explains how Unix timestamps actually work, the difference between seconds and milliseconds, how time zones fit into the picture, and the mistakes developers most commonly make.

What is a Unix timestamp?
Seconds vs milliseconds
JavaScript uses milliseconds
Does a Unix timestamp have a time zone?
UTC vs local time
ISO 8601 and Unix timestamps are different things
Common mistakes
- #1: Mixing seconds and milliseconds
- #2: Assuming the timestamp is in local time
- #3: Removing the UTC indicator
- #4: Manually applying time-zone offsets
- #5: Ignoring daylight saving time
- #6: Storing local time instead of an instant
Not every date should be a Unix timestamp
Negative Unix timestamps
What about the Year 2038 problem?
Notable Unix timestamps
Unix timestamp precision
Converting Unix timestamps in JavaScript
Debugging an unknown timestamp
A good rule for APIs
Practical rules to remember
Conclusion

What is a Unix timestamp?

A Unix timestamp represents the amount of time that has passed since January 1, 1970 at 00:00:00 UTC. This moment is commonly called the Unix epoch.

For example, 0 represents:

1970-01-01 00:00:00 UTC

A timestamp such as 1790186400 represents a specific moment after the Unix epoch:

2026-09-23 18:00:00 UTC

The important part is that the timestamp represents an instant in time, not a formatted date. A value such as 2026-09-23 18:00:00 is a human-readable representation. A Unix timestamp is simply a number.

Seconds vs milliseconds

One of the most common timestamp bugs comes from confusing seconds with milliseconds.

Traditional Unix timestamps use seconds since January 1, 1970. Many programming environments, however, use milliseconds. The same instant looks like this in each unit:

Seconds:      1790186400
Milliseconds: 1790186400000

Milliseconds usually have three extra digits. A quick rule of thumb:

10 digits -> usually seconds
13 digits -> usually milliseconds

This works for modern dates, but you should not rely on digit count as formal validation.

JavaScript uses milliseconds

JavaScript's Date API expects milliseconds:

const timestamp = 1790186400000
const date = new Date(timestamp)
console.log(date)

But many APIs return Unix timestamps in seconds:

const timestamp = 1790186400

If you pass that directly to Date, JavaScript interprets it as milliseconds, and the resulting date lands in January 1970:

new Date(1790186400) // 1970-01-21T17:16:26.400Z

Instead, convert seconds to milliseconds:

const timestamp = 1790186400
const date = new Date(timestamp * 1000)

The reverse operation works the same way. To get the current Unix timestamp in seconds:

const timestamp = Math.floor(Date.now() / 1000)

To get milliseconds:

const timestamp = Date.now()

Does a Unix timestamp have a time zone?

No. This is one of the most important things to understand about timestamps.

A Unix timestamp does not contain a time zone. It represents one exact instant in time.

For example, 1790186400 represents 2026-09-23 18:00:00 UTC. The exact same instant can be displayed as:

Location	Local time
Calgary	2026-09-23 12:00:00 MDT
New York	2026-09-23 14:00:00 EDT
London	2026-09-23 19:00:00 BST

The timestamp does not change. Only its formatted representation changes.

Think of a Unix timestamp as a position on a global timeline. A time zone only changes how that position is displayed to a person.

UTC vs local time

JavaScript makes this distinction visible:

const date = new Date(1790186400000)
console.log(date.toISOString())

toISOString() returns the date in UTC:

2026-09-23T18:00:00.000Z

The Z means UTC. But toString() uses the computer's local time zone:

console.log(date.toString())

A developer in Calgary might see something similar to:

Wed Sep 23 2026 12:00:00 GMT-0600 (Mountain Daylight Time)

Both values represent the exact same instant.

This difference is responsible for many apparent "timezone bugs". The timestamp is often correct — what changed is the way the application formatted it.

ISO 8601 and Unix timestamps are different things

Developers sometimes mix up Unix timestamps and ISO 8601 dates.

A Unix timestamp looks like 1790186400. An ISO 8601 date looks like 2026-09-23T18:00:00Z. They can both represent the same instant — the difference is representation.

Unix timestamps are compact and convenient for machines. ISO 8601 strings are easier for humans to read and can explicitly contain a UTC offset. For example, these two strings represent the same moment:

2026-09-23T12:00:00-06:00
2026-09-23T18:00:00Z

Common mistake #1: mixing seconds and milliseconds

Consider an API response:

{
  "created_at": 1790186400
}

You might write:

const createdAt = new Date(response.created_at)

This is wrong if created_at uses Unix seconds.

The correct version is:

const createdAt = new Date(response.created_at * 1000)

The reverse mistake happens as well. Suppose an API expects seconds, and you write:

const expiresAt = Date.now()

You send 1790186400000, but the server expects 1790186400. Read as seconds, your expiration date suddenly lands tens of thousands of years in the future.

When working with timestamps, always check the API documentation for the expected unit.

Common mistake #2: assuming the timestamp is in local time

A timestamp does not mean "12:00 Calgary time" or "14:00 New York time". It represents a global instant. The time zone matters only when converting that instant into a calendar date and clock time.

This distinction becomes especially important when users are located in different countries. For example, your database might store 1790186400, and the frontend then displays that timestamp in each user's own time zone. That is usually much safer than storing separately formatted local dates.

Common mistake #3: removing the UTC indicator

Consider this ISO string:

2026-09-23T18:00:00Z

The Z tells the parser that the value is UTC. Compare it with:

2026-09-23T18:00:00

There is no time-zone information here. Depending on the language, library, environment or parsing rules, the second value may be interpreted differently — in JavaScript, for example, a date-time string without an offset is parsed as local time.

When exchanging dates between systems, explicit time-zone information is much safer. Prefer formats such as:

2026-09-23T18:00:00Z
2026-09-23T12:00:00-06:00

instead of an ambiguous local date.

Common mistake #4: manually applying time-zone offsets

Imagine you receive a timestamp from an API and convert it to a JavaScript Date. JavaScript already knows how to display that date in the local time zone. A common mistake is then manually adding or subtracting an offset:

const date = new Date(timestamp * 1000)
date.setHours(date.getHours() - 6)

In many cases this applies the time-zone conversion twice.

It also breaks when daylight saving time changes.

Instead, keep the underlying timestamp unchanged and apply the desired time zone only when formatting the value:

const date = new Date(timestamp * 1000)

const formatted = new Intl.DateTimeFormat('en-CA', {
  dateStyle: 'medium',
  timeStyle: 'long',
  timeZone: 'America/Edmonton'
}).format(date)

console.log(formatted)

This is much safer than manually adding or subtracting hours.

Common mistake #5: ignoring daylight saving time

Time-zone offsets are not always constant. A location might use one UTC offset during part of the year and another during the rest of the year. Because of that, code such as:

timestamp - 6 * 60 * 60

should not be used as a general way to convert UTC to a local time zone. The correct offset may depend on:

location;
date;
daylight saving rules;
historical time-zone changes.

Use an actual IANA time-zone identifier instead:

America/Edmonton
America/New_York
Europe/London
Asia/Tokyo

Modern date/time libraries and Intl.DateTimeFormat apply the appropriate rules for you.

Common mistake #6: storing local time instead of an instant

Imagine a database field contains:

2026-09-23 12:00:00

What does that mean? 12:00 where — Calgary, Toronto, London, UTC? Without additional information, the value is ambiguous.

For events that represent an exact moment, storing either a Unix timestamp or an explicitly UTC-based datetime usually avoids this problem. Values such as 1790186400 or 2026-09-23T18:00:00Z can be converted into the user's preferred local time later.

Not every date should be a Unix timestamp

There is an important exception: some dates do not represent a global instant.

A birthday is a good example. If someone was born on 1990-05-15, you care about the calendar date, not an exact UTC moment. The same applies to:

birthdays;
anniversaries;
all-day calendar events;
billing dates;
holidays.

Converting every date into a timestamp can introduce unnecessary time-zone problems — a birthday stored as midnight UTC can show up as the previous day for users west of Greenwich. Choose the representation based on what the value actually means.

Negative Unix timestamps

Dates before January 1, 1970 are represented with negative timestamps. For example, -1 represents one second before the Unix epoch:

1969-12-31 23:59:59 UTC

Many modern systems support negative Unix timestamps, but behavior can differ between platforms and older libraries. If your application works with historical dates, test them explicitly. The lower limit of 32-bit time is covered in Unix timestamp -2147483648 and the 1901 limit.

What about the Year 2038 problem?

A signed 32-bit integer can store values only up to 2147483647. Interpreted as seconds since the Unix epoch, that limit is reached on January 19, 2038 at 03:14:07 UTC. Older systems that store timestamps as signed 32-bit integers overflow after that point.

Modern 64-bit systems do not have this practical limitation — a signed 64-bit timestamp in seconds covers a range far beyond anything normal applications need. However, the 2038 problem can still matter when working with:

legacy operating systems;
embedded systems;
old databases;
binary protocols;
older C applications.

Notable Unix timestamps

A few values come up again and again in logs, tests and bug reports:

Timestamp	Date (UTC)	Why it matters
`-2147483648`	1901-12-13 20:45:52	Signed 32-bit minimum and 2038 overflow target
`0`	1970-01-01 00:00:00	The Unix epoch, and why buggy dates show 1970
`1000000000`	2001-09-09 01:46:40	The billennium: timestamps become 10 digits
`1234567890`	2009-02-13 23:31:30	The famous sequential timestamp
`1700000000`	2023-11-14 22:13:20	Round-number milestones from 1.5 to 2.1 billion
`2000000000`	2033-05-18 03:33:20	The last round billion before 2038
`2147483647`	2038-01-19 03:14:07	The Year 2038 problem
`4294967295`	2106-02-07 06:28:15	The unsigned 32-bit limit and Year 2106

Unix timestamp precision

Unix-style timestamps can use different levels of precision. The same instant in each unit:

Seconds:      1790186400
Milliseconds: 1790186400000
Microseconds: 1790186400000000
Nanoseconds:  1790186400000000000

This is why receiving "a timestamp" from an API is not enough information. Before parsing it, check whether the value represents seconds, milliseconds, microseconds or nanoseconds.

Converting Unix timestamps in JavaScript

Timestamp in seconds to Date

const timestamp = 1790186400
const date = new Date(timestamp * 1000)

Timestamp in milliseconds to Date

const timestamp = 1790186400000
const date = new Date(timestamp)

Current Unix timestamp in seconds

const timestamp = Math.floor(Date.now() / 1000)

Current Unix timestamp in milliseconds

const timestamp = Date.now()

Date to Unix seconds

const date = new Date()
const timestamp = Math.floor(date.getTime() / 1000)

Convert to UTC ISO format

const date = new Date(1790186400000)
console.log(date.toISOString()) // 2026-09-23T18:00:00.000Z

Debugging an unknown timestamp

Suppose you find 1790186400 in a log and do not know what it means. A useful debugging process is:

Determine whether it is probably seconds, milliseconds, microseconds or nanoseconds.
Convert it into UTC.
Compare the result with the expected date.
Check whether the system displays the result in local time.
Look for any manually applied time-zone offsets.
Verify how the originating API or database documents the field.

For quick debugging, use the Unix Timestamp Converter to convert between Unix timestamps and human-readable dates in any time zone.

A good rule for APIs

When designing APIs, consistency matters more than which representation you choose. You might decide that your API always returns ISO 8601 strings:

{
  "created_at": "2026-09-23T18:00:00Z"
}

Or you might use Unix timestamps:

{
  "created_at": 1790186400
}

Both approaches work. Problems begin when one endpoint returns seconds (1790186400), another returns milliseconds (1790186400000), and a third returns a local datetime (2026-09-23 12:00:00) without documenting the difference.

Pick a convention and use it consistently across your API. The same applies to tokens: the exp, iat and nbf claims in a JWT are always Unix seconds, which you can check with the JWT Decoder.

Practical rules to remember

A Unix timestamp represents an instant in time.
Unix timestamps do not contain a time zone.
Traditional Unix timestamps use seconds.
JavaScript timestamps normally use milliseconds.
Do not apply fixed UTC offsets manually when you can use a real time-zone database.
Store exact moments in a time-zone-independent format.
Convert to the user's local time only when displaying the value.
Use explicit time-zone information when exchanging formatted datetime strings.
Always verify the timestamp unit used by an API.
Do not use timestamps for calendar-only dates unless you actually need an instant in time.

Conclusion

Unix timestamps are simple numbers, but the systems around them — time zones, daylight saving time, date formatting and different precision levels — make them surprisingly easy to misuse.

The most useful mental model is this:

A Unix timestamp identifies a point on the global timeline. A time zone only determines how that point is displayed.

Once you separate those two ideas, most timestamp problems become much easier to understand and debug.

Originally published at helpers.work.