DEV Community: Jules Smeets

JWTs in Elixir: fast parsing by plain pattern matching

Jules Smeets — Thu, 26 Mar 2026 21:35:01 +0000

JSON Web Tokens (JWTs) are the backbone of modern authentication. If you are building an API, chances are you are verifying a JWT on almost every single incoming request.

Because it happens so frequently, JWT verification is a prime candidate for optimization. But if you look at how standard JWT verification works, there is a lot of hidden overhead.

The Standard "Slow Path"

A JWT consists of three parts separated by dots: header.payload.signature. To verify a standard token, your application typically has to do the following:

Split the string by the . character using String.split/2 and/or regex.
Base64-decode the header.
Parse the resulting JSON string into a map.
Extract the kid (Key ID) and alg (Algorithm) claims.
Look up the correct public or symmetric key.
Verify the signature against the payload.

Steps 1 through 4 require allocating memory for new binaries, running a Base64 decoder, and firing up a JSON parser—all just to figure out which key to use.

If your application is minting its own tokens, 99% of the incoming requests are going to use your current, active signing key. Doing all that decoding and parsing on every request is wasted effort.

Our own header is always the same

The realization that speeds this up is simple: if you control the active signing key, the JWT header is entirely predictable.

Instead of extracting the token's header to find the key, we can flip the process upside down. We can pre-calculate exactly what the Base64-encoded header will look like for our active key, and use it to fast-track both signing and verifying tokens.

Setup: Caching the Header

The first step is to calculate the expected header at startup (or upon key rotation) and cache it. We use Erlang's :persistent_term for blazing fast, concurrent read access.

defmodule MyApp.Jwt do
  @doc "Run this at application startup or when rotating keys"
  def setup_fast_path(kid, alg \\ "HS256") do
    expected_header =
      # we need deterministic JSON with predictable key ordering
      ~s({"alg":"#{alg}","typ":"JWT","kid":"#{kid}"})
      |> Base.url_encode64(padding: false)

    :persistent_term.put(:jwt_header, expected_header)
  end
end

Fast-track verification

The real magic happens when checking incoming requests. We use Elixir's binary pattern matching to instantly route the token based on whether it starts with our cached header:

def verify(token) do
  expected_header = :persistent_term.get(:jwt_header, nil)

  case token do
    # Does the token start with our exact pre-calculated header?
    <<^expected_header::binary, ?., payload_and_sig::binary>> -> 
      fast_verify(payload_and_sig)

    # ... slow path fallback ...
    _ ->
      slow_verify(token)
  end
end

The binary pattern matching is Elixir at its finest. The VM doesn't need to split strings or allocate new memory to do so. It simply looks at the bytes of the incoming token, checks if they match the pinned expected_header variable followed by a . character, and assigns the rest of the binary to payload_and_sig. We now know the signing key and algorithm without parsing the header!

We are not done, however, and can take pattern matching one step further to split the payload and signature. This relies on two things: we know the signature's length in advance and can use byte_size/1 to determine the length of the whole (in constant time!):

# For HS256, the encoded signature is always exactly 43 characters
@hs256_sig_len 43

def fast_verify(payload_and_sig) do
  payload_len = byte_size(payload_and_sig) - @hs256_sig_len - 1

  case payload_and_sig do
    <<enc_payload::binary-size(payload_len), ?., enc_sig::binary-size(@hs256_sig_len)>> ->
      # We skipped String.split/2 entirely!
      # Now we just decode the payload and verify the signature...
      do_crypto_verify(enc_payload, enc_sig)

    _ ->
      {:error, :malformed_token}
  end
end

Signing

Of course, we can also use our precomputed header to speed up token signing (also leveraging iolists to prevent creating unnecessary intermediate binaries):

def sign(payload, key) do
  header = :persistent_term.get(:jwt_header, nil)
  enc_payload = payload |> JSON.encode!() |> Base.url_encode64(padding: false)
  mac_base = [header, ?., enc_payload]
  sig = :crypto.mac(:hmac, :sha256, key, mac_base) |> Base.url_encode64(padding: false)
  IO.iodata_to_binary([mac_base, ?., sig])
end

What if the header is not fully deterministic? Poly1305 and Base64 Magic

The optimization above works flawlessly for algorithms like HS256 or EdDSA. But what if you are using a MAC generated via Poly1305?

Poly1305 requires a unique nonce for every single invocation to remain secure. This means our JWT header suddenly needs to look like this:
{"alg":"Poly1305","typ":"JWT","nonce":"<random_string>","kid":"my_key"}

Because the nonce changes every time, we can no longer pre-calculate the entire Base64 encoded header. Does this mean we have to fall back to the slow path? Not if we use a little Base64 math.

Base64 works by encoding 3 bytes of raw data into 4 characters. If a string's byte length is exactly a multiple of 3, it encodes cleanly without padding (=) and without carrying over bits into the next character block. Such encoded strings can then be safely concatenated without invalidating the encoding!

We can exploit this by carefully crafting our JSON header so the static parts are multiples of 3 bytes:

Part 1: {"alg":"Poly1305","typ":"JWT","nonce":" (Length is 39, and 39 / 3 = 13. Perfect!)
Part 2: <dynamic_nonce>", (The nonce is 12 bytes, which encodes to 16 bytes. We add ", and part 2 is now 18 bytes - dividable by 3!)
Part 3: "kid": (Length is 6!)
Part 4: "my_key"} (The last part has no length requirement because nothing will be concatenated to its tail)

Because Parts 1, 2 and 3 are multiples of 3, we can safely pre-calculate their Base64 equivalents and concatenate them with the encoded dynamic bits later:

# Pre-encoded static chunks (safe to concatenate)
@p1305_h ~s({"alg":"Poly1305","typ":"JWT","nonce":") |> Base.url_encode64(padding: false)
@p1305_kid_seg ~s("kid":) |> Base.url_encode64(padding: false)

def setup_poly1305_fast_path(kid) do
  exp_htail = ~s("#{kid}"}) |> Base.url_encode64(padding: false)
  :persistent_term.put(:jwt_p1305_header, exp_htail)
end

Now, we can add a new pattern match to our verify/1 function to catch Poly1305 tokens. We just extract the encoded nonce_seg right out of the middle of the binary string:

def verify(token) do
  exp_header = :persistent_term.get(:jwt_header, nil)
  exp_htail  = :persistent_term.get(:jwt_p1305_header, nil)

  case token do
    # 1. The Simple Fast Path (HS256, etc)
    <<^exp_header::binary, ?., payload_and_sig::binary>> -> 
      fast_verify(payload_and_sig)

    # 2. The Base64 Magic Fast Path (Poly1305)
    <<@p1305_h, nonce_seg::binary-24, @p1305_kid_seg, ^exp_htail::binary, ?., payload_and_sig::binary>> ->
      fast_p1305_verify(nonce_seg, payload_and_sig)

    # 3. THE SLOW PATH
    _ -> 
      slow_verify(token)
  end
end

By ensuring our JSON keys and values add up to multiples of 3, we can continue to use Elixir's blazing fast binary pattern matching to route tokens, skipping the JSON parser entirely even when parts of the header are highly dynamic.

The Fallback

Of course, the slow path cannot be completely removed. If you rotate your signing keys, users with valid tokens signed by the old key will still need to access your API.

Because their tokens will have a different kid in the header, the fast path pattern match will naturally fail. The case statement falls back to slow_verify, which does the traditional Base64 decoding, JSON parsing, and dynamic key lookup.

The beauty of this architecture is that the fast path handles 99% of your traffic with near-zero overhead, while the slow path gracefully catches edge cases, legacy tokens, and key rotations without the caller ever needing to know the difference. And although we don't parse the headers, we don't assume anything here; because of the binary pattern matching, there's not a single header byte that is not exactly what we expect it to be. JWT-verification speed is improved by about 30% for normal-sized JWTs.

A real-world example (using only OTP!) that supports key rotation and multiple signing algorithms including HMAC-SHA256, EdDSA and Poly1305 can be found in Charon's JWT token factory.

Why We Stopped Using UUIDv4 in Elixir (And What We Built Instead)

Jules Smeets — Fri, 27 Feb 2026 18:14:21 +0000

If you’re building a new Phoenix application today, deciding on a primary key strategy usually takes about three seconds. You don't want to use standard auto-incrementing integers because they leak your business volume (e.g., "Oh, I'm only user #104? This app is a ghost town").

So, you do what everyone does: you reach for Ecto.UUID. It's built-in, it's unpredictable, and it solves the problem.

But as your application scales, UUIDv4 becomes a silent performance killer. After wrestling with database bloat and terrible API developer experience, we decided to build a better way. Enter Once.

Here is why we ditched UUIDs, and how you can get Stripe-style, high-performance IDs in your Elixir app in about two minutes.

The Problem with UUIDv4: Database Fragmentation

PostgreSQL (like most relational databases) uses B-trees for its indexes. B-trees are incredibly fast, but they have a distinct preference: they absolutely love sequential data.

When you insert a sequential ID (like a standard integer or a time-sorted Snowflake ID), Postgres cleanly appends it to the right edge of the index.

UUIDv4, however, is purely random. When you insert a million random UUIDs, Postgres has to constantly search for the correct leaf node to insert the new value. This causes massive "page splits," fragments the index, and destroys your cache locality.

Over time, your index size balloons, your write I/O skyrockets, and your database spends precious memory caching index pages that are mostly empty.

The API UX Problem: "Type Confusion"

Beyond database performance, UUIDs are completely hostile to human developers.

If you are looking at a log file or an API payload and see 9f1c0d3a-2b7e-49a1-8d5c-9123456789ab, what is it? Is it a User ID? A Payment ID? A Subscription ID? If a frontend developer accidentally passes an Organization ID into a User endpoint, the system will just return a generic 404 Not Found, leading to hours of frustrating debugging.

Stripe solved this years ago by prefixing their IDs: cus_... for customers, ch_... for charges. It is self-documenting, type-safe, and universally loved by developers. We wanted that exact experience in Ecto.

Enter `Once`: The Best of Both Worlds

We built Once as a custom Ecto type to solve both the database performance problem and the API usability problem, without compromising on security.

Under the hood, Once is powered by NoNoncense, a distributed, lock-free ID generator that uses Erlang's :atomics to generate tens of millions of 64-bit IDs per second. Because it's 64-bit (instead of UUID's 128-bit), it immediately cuts your ID storage footprint in half.

The "Masking" Magic

You usually have to make a painful choice:

Use sequential integers (Fast database, but leaks business metrics).
Use random strings (Protects metrics, but slow database).

With Once masking, you don't have to choose. You configure your Ecto schema to generate a sequential, counter-based ID. When Ecto saves the record to your database, it stores a raw, 64-bit integer. Your database is perfectly happy, and your B-tree indexes stay perfectly compact.

But when Ecto loads that record back into your Elixir application, Once uses blazing-fast encryption to transparently mask the integer, and prepends your chosen prefix.

As a standard bigint in your database: 98770186085072901
In your Elixir App / JSON API: "usr_4Tnk9-GqJ-s"

Your database gets perfectly optimized sequential writes. Your API consumers get unpredictable, Stripe-style, self-documenting strings.

Fully Composable: Pick What You Need

The best part about Once is that these features are fully composable and optional. You can tailor the ID generation to your exact needs:

Just want unique IDs? Use the defaults. You get 64-bit integers that are incredibly fast to generate and index in your database, and url64-encoded strings like "AV7m9gAAAAU" in Elixir.
Need chronological sorting? Change to nonce_type: :sortable. You get a Snowflake-like ID where the first 42 bits are a timestamp, meaning ORDER BY id works perfectly.
Want masked IDs? Just add mask: true.
Need true unpredictability at rest? If you don't want to use masking and genuinely need UUIDv4-style randomness stored in your database, switch to nonce_type: :encrypted.
Want Prefixes? Just add prefix: "req_" to any of the above.
Want to persist the prefix? Use a binary database format like db_format: :hex and add persist_prefix: true.
Want a different API format like integers? Use ex_format: :unsigned to render IDs like "usr_98770186085072901"

You can combine all of these as you see fit, and automagically generate distributed IDs with just the features that you need and nothing more.

Why not UUIDv7?

While UUIDv7 solves the index fragmentation problem, it's not as flexible as Once:

Storage: UUIDv7 is still a bloated 128-bit identifier. Once cuts that in half (64-bit).
API UX: UUIDv7 still looks like a massive, unreadable string (018e4b...). Once gives you Stripe-style usr_... prefixes.
Business Leakage/Security: UUIDv7 visibly leaks the exact millisecond a record was created. Once uses masking to hide the underlying counter/timestamp entirely.

The 2-Minute Phoenix Quickstart

Here is how easy it is to drop into a Phoenix project.

1. Add the dependencies to mix.exs:

def deps do
  [
    {:once, "~> 1.2"}
  ]
end

2. Initialize the generator in your application.ex:

# Create a unique Machine ID for this node (supports up to 512 nodes in a cluster)
machine_id = NoNoncense.MachineId.id!(node_list: [Node.self()])

# Initialize a NoNoncense instance for Once with a secret key for masking
# (Pull this from your environment in production!)
secret_key = System.get_env("ONCE_SECRET_KEY", "my supersecret dev key")
NoNoncense.init(name: Once, machine_id: machine_id, base_key: secret_key)

Note that NoNoncense is not a GenServer; it keeps its write-once-read-often state in :persistent_term.

3. Define your Ecto Schema:
Just set Once as your primary key, give it a prefix, and turn on masking.

defmodule MyApp.Accounts.User do
  use Ecto.Schema

  @primary_key {:id, Once, autogenerate: true, prefix: "usr_", mask: true}
  schema "users" do
    field :email, :string
    timestamps()
  end
end

That’s it. You now have locally unique (within your app or domain), Stripe-prefixed, cryptographically masked 64-bit IDs that won't destroy your database indexes.

If you’re tired of the UUID performance tax or just want a better developer experience for your API consumers, give Once a try on your next project.

Check out the full documentation and advanced configuration options on HexDocs for Once and NoNoncense.