Secrets Manager

function getSecret<T>(name: string, options?: SecretsGetOptions): Promise<T | undefined>;

class SecretsProvider extends BaseProvider {
  constructor(config?: SecretsProviderOptions);
  get<T>(name: string, options?: SecretsGetOptions): Promise<T | undefined>;
}

interface SecretsGetOptions {
  maxAge?: number;
  forceFetch?: boolean;
  transform?: 'json' | 'binary';
  sdkOptions?: Omit<Partial<GetSecretValueCommandInput>, 'SecretId'>;
}

type SecretsProviderOptions = { clientConfig?: SecretsManagerClientConfig } | { awsSdkV3Client?: SecretsManagerClient };

import { getSecret } from '@aws-lambda-powertools/parameters/secrets';

// By name
const secret = await getSecret('my-secret');

// By ARN
const secretArn = await getSecret('arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret-abc123');

// Parse JSON
interface DBCreds { username: string; password: string; host: string; port: number; }
const creds = await getSecret<DBCreds>('db-creds', { transform: 'json' });

// Decode binary
const binarySecret = await getSecret('my-binary-secret', { transform: 'binary' });

// Custom cache
const cached = await getSecret('my-secret', { maxAge: 300, forceFetch: true });

// Specific version
const versioned = await getSecret('my-secret', {
  sdkOptions: { VersionId: 'version-uuid' }
});

// Current version (default)
const current = await getSecret('rotated-secret', {
  sdkOptions: { VersionStage: 'AWSCURRENT' }
});

// Previous version (during rotation)
const previous = await getSecret('rotated-secret', {
  sdkOptions: { VersionStage: 'AWSPREVIOUS' }
});

import { SecretsProvider } from '@aws-lambda-powertools/parameters/secrets';
import { SecretsManagerClient } from '@aws-sdk/client-secrets-manager';

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

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

// Custom client (for X-Ray tracing, etc.)
const client = new SecretsManagerClient({ region: 'eu-west-1' });
const providerWithClient = new SecretsProvider({ awsSdkV3Client: client });

// Use provider
const apiKey = await provider.get('api-key', { maxAge: 3600 });
const config = await provider.get('db/config', { transform: 'json' });

// Cache management
provider.clearCache(); // e.g., after rotation
if (provider.hasKeyExpiredInCache('api-key')) console.log('Expired');

// Multiple regions
const usProvider = new SecretsProvider({ clientConfig: { region: 'us-east-1' } });
const euProvider = new SecretsProvider({ clientConfig: { region: 'eu-west-1' } });

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["secretsmanager:GetSecretValue"],
      "Resource": ["arn:aws:secretsmanager:region:account-id:secret:secret-name-*"]
    },
    {
      "Effect": "Allow",
      "Action": ["kms:Decrypt"],
      "Resource": ["arn:aws:kms:region:account-id:key/key-id"]
    }
  ]
}