Systems Manager Parameter Store

function getParameter<T>(name: string, options?: SSMGetOptions): Promise<T | undefined>;
function getParameters<T>(path: string, options?: SSMGetMultipleOptions): Promise<Record<string, T> | undefined>;
function getParametersByName<T>(parameters: Record<string, SSMGetParametersByNameOptions>, options?: SSMGetParametersByNameOptions): Promise<SSMGetParametersByNameOutput<T>>;
function setParameter(name: string, options: SSMSetOptions): Promise<number>;

class SSMProvider extends BaseProvider {
  constructor(config?: SSMProviderOptions);
  get<T>(name: string, options?: SSMGetOptions): Promise<T | undefined>;
  getMultiple<T>(path: string, options?: SSMGetMultipleOptions): Promise<Record<string, T> | undefined>;
  getParametersByName<T>(parameters: Record<string, SSMGetParametersByNameOptions>, options?: SSMGetParametersByNameOptions): Promise<SSMGetParametersByNameOutput<T>>;
  set(name: string, options: SSMSetOptions): Promise<number>;
}

interface SSMGetOptions {
  maxAge?: number;
  forceFetch?: boolean;
  transform?: 'json' | 'binary';
  sdkOptions?: Partial<GetParameterCommandInput>;
  decrypt?: boolean;
}

interface SSMGetMultipleOptions {
  maxAge?: number;
  forceFetch?: boolean;
  transform?: 'json' | 'binary' | 'auto';
  sdkOptions?: Partial<GetParametersByPathCommandInput>;
  decrypt?: boolean;
  recursive?: boolean;
  throwOnTransformError?: boolean;
}

interface SSMGetParametersByNameOptions {
  maxAge?: number;
  throwOnError?: boolean;
  decrypt?: boolean;
  transform?: 'json' | 'binary';
}

type SSMGetParametersByNameOutput<T> = Record<string, T | unknown> & { _errors?: string[] };

interface SSMSetOptions {
  value: string;
  overwrite?: boolean;
  description?: string;
  parameterType?: 'String' | 'StringList' | 'SecureString';
  tier?: 'Standard' | 'Advanced' | 'Intelligent-Tiering';
  kmsKeyId?: string;
  sdkOptions?: Partial<PutParameterCommandInput>;
}

type SSMProviderOptions = { clientConfig?: SSMClientConfig } | { awsSdkV3Client?: SSMClient };

import { getParameter } from '@aws-lambda-powertools/parameters/ssm';

// Basic retrieval
const apiUrl = await getParameter('/my/api/url');

// With decryption
const dbPassword = await getParameter('/my/db/password', { decrypt: true });

// Parse JSON
const config = await getParameter('/my/config', { transform: 'json' });

// Custom cache
const value = await getParameter('/my/param', { maxAge: 60, forceFetch: true });

import { getParameters } from '@aws-lambda-powertools/parameters/ssm';

// Get all under path
const params = await getParameters('/my/service/config');
for (const [key, value] of Object.entries(params || {})) {
  console.log(`${key}: ${value}`);
}

// Recursive with auto-transform (detects .json suffix)
const configs = await getParameters('/my/path', {
  recursive: true,
  transform: 'auto'
});

// With decryption
const secrets = await getParameters('/my/secrets', { decrypt: true, recursive: true });

import { getParametersByName } from '@aws-lambda-powertools/parameters/ssm';

// Individual config per parameter
const params = await getParametersByName({
  '/prod/db/host': { maxAge: 300 },
  '/prod/db/port': { maxAge: 300 },
  '/prod/api/config': { transform: 'json' }
});

// With default options
const p = await getParametersByName(
  { '/app/p1': {}, '/app/p2': { transform: 'json' } },
  { maxAge: 60, decrypt: true }
);

// Non-throwing mode (collect errors in result._errors)
const result = await getParametersByName(
  { '/valid': {}, '/missing': {} },
  { throwOnError: false }
);
if (result._errors?.length > 0) console.error('Errors:', result._errors);

import { setParameter } from '@aws-lambda-powertools/parameters/ssm';

// Basic
const version = await setParameter('/my/param', { value: 'my-value' });

// Update existing
await setParameter('/my/param', { value: 'new-value', overwrite: true });

// Secure string with KMS
await setParameter('/my/secret', {
  value: 'secret-value',
  parameterType: 'SecureString',
  kmsKeyId: 'alias/my-key',
  description: 'My secret'
});

// Advanced tier
await setParameter('/my/large/param', {
  value: largeValue,
  tier: 'Advanced',
  overwrite: true
});

// String list
await setParameter('/my/list', {
  value: 'value1,value2,value3',
  parameterType: 'StringList'
});

import { SSMProvider } from '@aws-lambda-powertools/parameters/ssm';
import { SSMClient } from '@aws-sdk/client-ssm';

// Default config
const provider = new SSMProvider();

// Custom region
const customProvider = new SSMProvider({
  clientConfig: { region: 'us-west-2', maxAttempts: 3 }
});

// Custom client instance
const client = new SSMClient({ region: 'eu-west-1' });
const providerWithClient = new SSMProvider({ awsSdkV3Client: client });

// Use provider
const value = await provider.get('/my/param', { maxAge: 300, decrypt: true });
const values = await provider.getMultiple('/my/path', { recursive: true });
await provider.set('/my/param', { value: 'new', overwrite: true });

// Cache management
provider.clearCache();
if (provider.hasKeyExpiredInCache('/my/param')) console.log('Expired');

// Explicit type
const config = await getParameter<MyConfig>('/config', { transform: 'json' });

// Inferred from transform
const jsonData = await getParameter('/data', { transform: 'json' }); // JSONValue
const binaryData = await getParameter('/data', { transform: 'binary' }); // string
const stringData = await getParameter('/data'); // string

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["ssm:GetParameter", "ssm:GetParameters", "ssm:GetParametersByPath", "ssm:PutParameter"],
      "Resource": ["arn:aws:ssm:region:account-id:parameter/path/*"]
    },
    {
      "Effect": "Allow",
      "Action": ["kms:Decrypt"],
      "Resource": ["arn:aws:kms:region:account-id:key/key-id"]
    }
  ]
}