@akeyless-community/heroku-runtime

Fetch Akeyless secrets at runtime on Heroku dynos (Node.js). Application secrets stay in Akeyless — only bootstrap auth config vars are set on the app.

Works standalone or with the Akeyless Heroku add-on (heroku addons:create akeyless).

Install

npm install @akeyless-community/heroku-runtime

Requires Node.js 18+.

Quick start

1. Provision the add-on (recommended)

heroku addons:create akeyless:starter -a my-app

The add-on injects bootstrap config vars (auth + path prefix). Store application secrets in Akeyless:

/heroku/my-app/production/DATABASE_URL
/heroku/my-app/production/STRIPE_SECRET_KEY

2. Fetch secrets in your app

const express = require('express');
const { getSecret } = require('@akeyless-community/heroku-runtime');

const app = express();

app.get('/health', async (_req, res) => {
  const dbUrl = await getSecret('DATABASE_URL');
  res.json({ ok: true, hasDb: Boolean(dbUrl) });
});

app.listen(process.env.PORT || 3000);

Use getSecret only in server code (web dynos, workers, one-off dynos). Never expose fetched secrets to the browser.

3. Manual setup (without add-on)

Set bootstrap config vars yourself:

| Config var | Required | Example | |------------|----------|---------| | AKEYLESS_ACCESS_ID | Yes* | p-xxxxx | | AKEYLESS_ACCESS_KEY | Yes* | access key secret | | AKEYLESS_SECRET_PREFIX | Recommended | /heroku/my-app/production | | AKEYLESS_GATEWAY_URL | No | https://api.akeyless.io |

* Or use another auth method below.

If AKEYLESS_SECRET_PREFIX is omitted, the library derives it from Heroku metadata:

/heroku/{HEROKU_APP_NAME}/{HEROKU_APP_ENV}

Per-environment prefixes

| Heroku environment | Typical prefix | |--------------------|----------------| | production | /heroku/my-app/production | | staging | /heroku/my-app/staging | | review apps | /heroku/my-app/review |

Set AKEYLESS_SECRET_PREFIX explicitly when you need a custom layout.

API

Convenience (singleton, dyno-friendly)

const { getSecret, getDefaultClient } = require('@akeyless-community/heroku-runtime');

const dbUrl = await getSecret('DATABASE_URL');

Explicit client

const { createClient } = require('@akeyless-community/heroku-runtime');

const client = createClient({
  gatewayUrl: 'https://api.akeyless.io',
  secretPrefix: '/heroku/my-app/production',
  accessId: process.env.AKEYLESS_ACCESS_ID,
  accessKey: process.env.AKEYLESS_ACCESS_KEY,
});

await client.getSecret('DATABASE_URL');
await client.getSecretAtPath('/custom/full/path');
await client.getDynamicSecret('db-creds');
await client.getRotatedSecret('rotated-api-key');

Authentication

Configure via Heroku config vars or createClient({ ... }).

| Method | AKEYLESS_ACCESS_TYPE | Additional config | |--------|------------------------|-------------------| | Access key (default) | access_key | AKEYLESS_ACCESS_ID, AKEYLESS_ACCESS_KEY | | API key | api_key | AKEYLESS_ACCESS_ID, AKEYLESS_ACCESS_KEY | | Universal Identity | universal_identity | AKEYLESS_UID_TOKEN | | JWT | jwt | AKEYLESS_ACCESS_ID, AKEYLESS_JWT | | AWS IAM | aws_iam | AKEYLESS_ACCESS_ID, optional AKEYLESS_CLOUD_ID | | Pre-authenticated | — | AKEYLESS_TOKEN |

Use a dedicated Akeyless auth method with read-only access to your /heroku/... path.

Add-on config var prefix

Heroku add-ons expose config vars with a prefix (default: AKEYLESS_). If you attach the add-on with a custom prefix:

heroku addons:create akeyless:starter --as SECRETS -a my-app

Set AKEYLESS_ADDON_PREFIX=SECRETS so the runtime reads SECRETS_ACCESS_ID, etc.

Caching

• Auth tokens refresh before expiry (default margin: 1 minute).
• Secret values cache in memory for 5 minutes by default (AKEYLESS_SECRET_CACHE_TTL_MS).
• Long-lived web/worker dynos reuse the module singleton.

Lower TTL or use ignoreCache: true for frequently rotated secrets.

Example app

npm run build
cd examples/express && npm install
heroku local  # or set AKEYLESS_* env vars locally
npm start

Local development

export AKEYLESS_ACCESS_ID=p-xxxxx
export AKEYLESS_ACCESS_KEY=your-key
export AKEYLESS_SECRET_PREFIX=/heroku/my-app/development
export HEROKU_APP_NAME=my-app
export HEROKU_APP_ENV=development

Or use Heroku Local:

heroku config -s -a my-app > .env

Related community projects

• heroku-akeyless-addon — Heroku Elements add-on partner API
• @akeyless-community/vercel-runtime — Vercel runtime secrets
• @akeyless-community/railway-runtime — Railway runtime secrets
• buildkite-akeyless-plugin — CI secret injection

License

Apache-2.0