Upgrading to Lockspire v1.27

Copy Markdown

This guide covers the one operator-visible behavior change in v1.27 that may affect tokens issued to your clients: the default access-token issuance format flipped from opaque to :jwt.

If every one of your clients already pins access_token_format explicitly, nothing changes for you — skip to Who is affected to confirm, then you are done.

What changed: the default issuance format flipped to :jwt

In v1.26 and earlier, the server-wide default access-token format was opaque. As of v1.27 the server-wide default access_token_format is :jwt. The authorization-code, refresh, device, and CIBA grant paths now mint RFC 9068 at+jwt access tokens by default instead of opaque tokens.

This is a default-value change (a flip), not a removal: opaque issuance is still fully supported. It is now opt-in (per client, or server-wide) rather than the implicit default.

Who is affected

The default only applies to a client that has not pinned its own format. Concretely, the affected set is:

Every client whose access_token_format is nil.

A client with access_token_format: nil inherits the server-wide default, so on v1.27 it begins receiving :jwt (at+jwt) access tokens where it previously received opaque ones.

Clients that carry an explicit :opaque override are NOT affected — their behavior is unchanged, and they continue to receive opaque tokens. The same is true for clients with an explicit :jwt override (already :jwt).

Format precedence

The effective format for any issuance is resolved with this precedence (authoritative source: the internal AccessTokenSigner resolve-format helper):

  1. The client's own access_token_format if it is :jwt or :opaque (an explicit per-client override always wins).
  2. Otherwise (the client's access_token_format is nil), the server-wide ServerPolicy.access_token_format — which now defaults to :jwt.
  3. If neither is set, :jwt.

Run mix lockspire.doctor token_format to see the resolved effective format for every client and which ones changed under the new default.

Opting back to opaque

If you need to restore opaque issuance for the whole deployment, set the server-wide format back to opaque with a single runtime call:

Lockspire.Admin.ServerPolicy.put_access_token_format(:opaque)

This updates the durable runtime ServerPolicy record immediately and applies to every nil-format client (clients with explicit overrides keep their override either way).

There is NO config :lockspire key for this

The server-wide access-token format is durable runtime ServerPolicy state (introduced in Phase 99), not a boot-time configuration value. There is no config :lockspire key for the access-token format. Editing config/*.exs to try to change it would be a silent no-op — the runtime ServerPolicy record is the only source of truth.

Always use the runtime call above (put_access_token_format(:opaque)) to change the server-wide default.

Summary

  • The server-wide default access_token_format flipped from opaque to :jwt.
  • Affected clients are exactly those whose access_token_format is nil (they inherit the new :jwt default).
  • Clients with an explicit :opaque override are unaffected.
  • Opt the whole deployment back with the runtime call Lockspire.Admin.ServerPolicy.put_access_token_format(:opaque).
  • There is no config :lockspire key for this; a config edit is a no-op.