@akeyless-community/netlify-runtime

Fetch Akeyless secrets at runtime on Netlify (Node.js). No sync to Netlify environment variables — Akeyless stays the source of truth.

Works standalone or with the Akeyless Netlify integration.

Install

npm install @akeyless-community/netlify-runtime

Requires Node.js 18+ and Netlify Functions (not Edge Functions).

Quick start

1. Bootstrap env vars in Netlify

Set only auth + path prefix (not application secrets):

| Variable | Required | Example | |----------|----------|---------| | AKEYLESS_ACCESS_ID | Yes* | p-xxxxx | | AKEYLESS_ACCESS_KEY | Yes* | access key secret | | AKEYLESS_SECRET_PREFIX | Recommended | /netlify/my-site/production | | AKEYLESS_GATEWAY_URL | No | https://api.akeyless.io |

* Or use another auth method below.

Organize secrets in Akeyless:

/netlify/my-site/production/DATABASE_URL
/netlify/my-site/production/STRIPE_SECRET_KEY

2. Fetch in a Netlify Function

// netlify/functions/checkout.ts
import type { Handler } from '@netlify/functions';
import { getSecret } from '@akeyless-community/netlify-runtime';

export const handler: Handler = async () => {
  const stripeKey = await getSecret('STRIPE_SECRET_KEY');
  return {
    statusCode: 200,
    body: JSON.stringify({ ok: true, hasStripe: Boolean(stripeKey) }),
  };
};

Use getSecret only in server code (Functions, server-side rendering). Never import in client bundles.

3. Per-deploy-context prefix

Set AKEYLESS_SECRET_PREFIX per deploy context in the Netlify UI, or let the library derive it from Netlify metadata:

/netlify/{SITE_NAME}/{CONTEXT}

| Netlify CONTEXT | Typical prefix | |-------------------|----------------| | production | /netlify/my-site/production | | deploy-preview | /netlify/my-site/deploy-preview | | branch-deploy | /netlify/my-site/branch-deploy | | dev | /netlify/my-site/dev |

API

Convenience (singleton, warm-invocation friendly)

import { getSecret } from '@akeyless-community/netlify-runtime';

const dbUrl = await getSecret('DATABASE_URL');

Explicit client

import { createClient } from '@akeyless-community/netlify-runtime';

const client = createClient({
  gatewayUrl: 'https://api.akeyless.io',
  secretPrefix: '/netlify/my-site/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

| Method | AKEYLESS_ACCESS_TYPE | Additional env | |--------|------------------------|----------------| | 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 | | Azure AD | azure_ad | AKEYLESS_ACCESS_ID, optional AKEYLESS_CLOUD_ID | | GCP | gcp | AKEYLESS_ACCESS_ID, optional AKEYLESS_CLOUD_ID | | Pre-authenticated | — | AKEYLESS_TOKEN |

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

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).
• Warm function invocations reuse the same module singleton.

Local development

export AKEYLESS_ACCESS_ID=p-xxxxx
export AKEYLESS_ACCESS_KEY=your-key
export AKEYLESS_SECRET_PREFIX=/netlify/my-site/dev
netlify dev

Limitations

• Node.js Functions only — the akeyless SDK does not run on Netlify Edge Functions.
• Network — functions must reach your Akeyless gateway (api.akeyless.io or self-hosted).
• Build-time secrets — for build-time injection, use the Akeyless Netlify integration push-sync mode.

Related community projects

• netlify-akeyless-integration — Netlify SDK integration for secret sync
• vercel-akeyless-runtime — Vercel runtime pull
• heroku-akeyless-runtime — Heroku runtime pull

License

Apache-2.0