@akeyless-community/vercel-runtime

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

Repository: github.com/akeyless-community/vercel-akeyless-runtime

Install

npm install @akeyless-community/vercel-runtime

Requires Node.js 18+ and the Node.js runtime on Vercel (not Edge).

Quick start (Next.js)

1. Bootstrap env vars in Vercel

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 | /vercel/my-app/production | | AKEYLESS_GATEWAY_URL | No | https://api.akeyless.io |

* Or use another auth method below.

Organize secrets in Akeyless:

/vercel/my-app/production/DATABASE_URL
/vercel/my-app/production/STRIPE_SECRET_KEY

2. Fetch in a server route

// app/api/checkout/route.ts
import { getSecret } from '@akeyless-community/vercel-runtime';

export const runtime = 'nodejs';

export async function POST() {
  const stripeKey = await getSecret('STRIPE_SECRET_KEY');
  // ...
}

Use getSecret only in server code (Route Handlers, Server Actions, getServerSideProps). Never import in client components.

3. Per-environment prefix

Set AKEYLESS_SECRET_PREFIX per Vercel environment in the dashboard:

• Production: /vercel/my-app/production
• Preview: /vercel/my-app/preview
• Development: /vercel/my-app/development

API

Convenience (singleton, warm-invocation friendly)

import { getSecret, getDefaultClient } from '@akeyless-community/vercel-runtime';

const dbUrl = await getSecret('DATABASE_URL');

Explicit client

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

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

Static with dynamic fallback

await client.getSecret('db-creds', { allowDynamicFallback: true });

Bypass cache (rotation-sensitive)

await client.getSecret('API_KEY', { ignoreCache: true });

Authentication

Configure via environment variables or createClient({ ... }).

| 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 /vercel/... path.

Vercel OIDC → AWS IAM (no Akeyless access key in Vercel)

Recommended for production: bootstrap with AWS role + Akeyless access ID only.

1. Enable Vercel OIDC on the project.
2. Create an AWS IAM role trusted by oidc.vercel.com with AssumeRoleWithWebIdentity.
3. Bind an Akeyless AWS IAM auth method to that role.
4. Install the optional peer dependency:

npm install @vercel/oidc-aws-credentials-provider

5. Use the built-in helper:

import { createClientWithVercelOidc } from '@akeyless-community/vercel-runtime';

export const runtime = 'nodejs';

export async function GET() {
  const client = await createClientWithVercelOidc();
  const dbUrl = await client.getSecret('DATABASE_URL');
  // ...
}

Set in Vercel:

| Variable | Value | |----------|-------| | AWS_ROLE_ARN | IAM role ARN trusted by Vercel OIDC | | AKEYLESS_ACCESS_ID | Akeyless AWS IAM auth access ID | | AKEYLESS_SECRET_PREFIX | /vercel/my-app/production |

Subpath import (same API):

import { createClientWithVercelOidc } from '@akeyless-community/vercel-runtime/oidc';

See examples/nextjs for a working Next.js app with both access-key and OIDC routes.

On AWS Lambda with an execution role, omit cloudId when using createClient({ accessType: 'aws_iam' }) — akeyless-cloud-id uses ambient credentials automatically.

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 Vercel invocations reuse the same module singleton (getSecret / getDefaultClient).

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

Example app

npm run build
cd examples/nextjs && npm install
# set AKEYLESS_* env vars — see examples/nextjs/README.md
npm run dev

Local development

export AKEYLESS_ACCESS_ID=p-xxxxx
export AKEYLESS_ACCESS_KEY=your-key
export AKEYLESS_SECRET_PREFIX=/vercel/my-app/development

Or pull Vercel env locally:

vercel env pull .env.local

Limitations

• Node.js runtime only — the akeyless SDK does not run on Vercel Edge.
• Network — functions must reach your Akeyless gateway (api.akeyless.io or self-hosted).
• NEXT_PUBLIC_* — values baked into the client bundle still need build-time resolution; keep those non-secret or accept build-time fetch.

Related community projects

• @akeyless-community/railway-runtime — Railway runtime secrets
• buildkite-akeyless-plugin — CI secret injection
• retool-akeyless-bridge — external secrets backend adapter

License

Apache-2.0