Keystore vaults

When AuthKit runs with a managed JWKS (jwks: { source: 'managed' }), it generates the RS256/ES256 signing key on first boot, persists the private keystore, and rotates it on demand. Where that private keystore lives is the single most security-sensitive storage decision in the whole system — anyone who can read it can mint tokens your relying parties will trust.

That decision is expressed in one place: jwks.store. It accepts a small tagged union — a filesystem path, one of five built-in drivers, or one of three cloud secrets managers delivered as companion packages. This page documents every variant, then the three cloud packages in detail.

The jwks.store config surface

store is a union of nine forms: a bare string (a shortcut), five built-in drivers, and three cloud drivers. Every form is a plain object literal with a driver discriminator, so your editor narrows the remaining fields as soon as you type the driver name.

String shortcut — a file path

The shortest form. A string is exactly equivalent to { driver: 'file', path: <string> }:

jwks: {
  source: 'managed',
  algorithm: 'RS256',
  store: 'tmp/authkit_jwks.json',
}

Relative paths resolve against the application root (the same base as app.makePath), so tmp/authkit_jwks.json lands next to your project, not next to node_modules.

file

The explicit spelling of the shortcut. The file is created with mode 0600 and the parent directory is created recursively on first write. Change detection for the reload poller uses the file's modification time.

store: { driver: 'file', path: 'storage/authkit/jwks.json' },

drive

Persists the blob as an object on an @adonisjs/drive disk — S3, GCS, or the local driver. Change detection prefers the object's ETag and falls back to its last-modified timestamp.

store: { driver: 'drive', disk: 's3', key: 'authkit/jwks.json' },

@adonisjs/drive is an optional peer. Unlike the avatar storage, which degrades quietly when Drive is missing, the keystore does not: selecting driver: 'drive' without the package installed throws at boot. A signing key is too important to silently fall back on.

lucid

A one-row key/value table, shared by every instance pointing at the same database — so multi-instance works with no extra infrastructure. The table is created on the first write if it does not exist, including under a boot race between instances.

store: { driver: 'lucid', connection: 'pg', table: 'authkit_keystore', key: 'jwks' },

The auto-create is deliberate rather than a convenience: the keystore is read while the config resolves, which happens before the provider's schema management runs. The vault therefore cannot assume its own table already exists. Reads against a missing table return "no keystore yet" instead of throwing.

redis

Also shared across instances, and the cheapest to poll — change detection is a plain GET.

store: { driver: 'redis', connection: 'main', key: 'authkit:jwks' },

hashicorp-vault

Talks to a HashiCorp Vault KV v2 engine over its HTTP API — no SDK, no extra dependency. Reads hit {endpoint}/v1/{mount}/data/{path} and change detection reads current_version from {endpoint}/v1/{mount}/metadata/{path}.

store: {
  driver: 'hashicorp-vault',
  endpoint: 'https://vault.acme.internal:8200',
  path: 'authkit/jwks',
  mount: 'secret',
  field: 'value',
  token: env.get('VAULT_TOKEN'),
},

A 404 is read as "not written yet" and produces the initial key. Any other non-OK status throws rather than degrading — a transient Vault outage must not be mistaken for an empty keystore, because that would silently mint a replacement key.

aws-secrets-manager

Requires @adonis-agora/authkit-vault-aws plus its optional peer @aws-sdk/client-secrets-manager (>=3).

store: {
  driver: 'aws-secrets-manager',
  secretId: 'prod/authkit/jwks',
  region: 'us-east-1',
},

The first write creates the secret if it does not exist; subsequent writes add a version. Change detection uses the secret's VersionId.

gcp-secret-manager

name is the secret resource name, projects/{project}/secrets/{secret} — without a version suffix. AuthKit reads {name}/versions/latest and writes by adding a new version to that secret. Requires @adonis-agora/authkit-vault-gcp plus its optional peer @google-cloud/secret-manager (>=5).

store: {
  driver: 'gcp-secret-manager',
  name: 'projects/acme-prod/secrets/authkit-jwks',
},

Credentials come from Application Default Credentials — the same resolution the Google SDK uses everywhere else, so a workload-identity service account needs no extra config here. Change detection uses the resolved version's resource name.

azure-key-vault

Requires @adonis-agora/authkit-vault-azure plus its optional peers @azure/keyvault-secrets (>=4) and @azure/identity (>=4).

store: {
  driver: 'azure-key-vault',
  vaultUrl: 'https://acme-prod.vault.azure.net',
  secretName: 'authkit-jwks',
},

Authentication goes through DefaultAzureCredential, so managed identity, environment variables, or a developer's az login all work without a code change. Change detection uses the secret version.

How a cloud driver is loaded

The three cloud packages are companions, not dependencies. authkit-server never imports them statically; the driver name in your config is what pulls one in. What you can rely on:

The shared contract

All three packages export the same two types, and implement the same tiny interface — the structural shape AuthKit's keystore consumes:

/** What createKeystoreVault returns — the shape authkit-server's keystore consumes. */
export interface KeystoreVaultLike {
  /** Read the persisted keystore blob, or null if it doesn't exist yet. */
  read(): Promise<string | null>
  /** Persist (create-or-update) the keystore blob. */
  write(blob: string): Promise<void>
  /** Cheap change token (version/etag) for the live-reload poller. Optional. */
  head?(): Promise<string | null>
}

Each factory composes a small, injectable SecretBackend seam, so the cloud SDK calls are isolated and unit-testable without any live cloud:

/** get/put/version — the minimal cloud-secret surface each package adapts to. */
export interface SecretBackend {
  get(): Promise<string | null>
  put(blob: string): Promise<void>
  version?(): Promise<string | null>
}

createKeystoreVault(config) returns a KeystoreVaultLike whose read/write delegate to backend.get/backend.put, and whose head() prefers backend.version() (a cheap version id) falling back to a full get(). Passing your own backend in the config bypasses the cloud SDK entirely — handy for tests or a bespoke transport:

import { createKeystoreVault } from '@adonis-agora/authkit-vault-aws'

const vault = createKeystoreVault({
  secretId: 'prod/authkit/jwks',
  backend: {
    async get() {
      /* return the blob from wherever you like */
      return null
    },
    async put(blob) {
      /* persist it */
    },
    async version() {
      return 'v1'
    },
  },
})

Encryption at rest

AuthKit can also encrypt the keystore blob with your APP_KEY before persisting it (jwks.encrypt). The default is backend-aware, and the split is about whether the backend is a secret manager or a dumb blob store:

Set it explicitly when you want defense in depth (app-layer encryption and the vault's own):

jwks: {
  source: 'managed',
  encrypt: true, // APP_KEY-encrypt the blob before it reaches the vault
  store: { driver: 'gcp-secret-manager', name: 'projects/acme/secrets/authkit-jwks' },
}

Rotation

Rotation is identical regardless of the backend — the store is just where the blob lands. Run the command (or the Key Rotation admin panel) and the new key is written straight to the configured backend:

node ace authkit:keys:rotate            # rotate, keeping 2 keys (grace period)
node ace authkit:keys:rotate --dry-run  # print the plan, write nothing
node ace authkit:keys:rotate --keep=3   # keep 3 keys in the published JWKS
node ace authkit:keys:rotate --retire   # keep only the new key

The new key goes to the front of the keyset and becomes the signing key; the retained older keys stay in the published JWKS so tokens signed before the rotation keep validating until they expire. --retire skips that grace window and invalidates them immediately.

See Signing key rotation for the full flag reference.

Pick your cloud to continue: