Token Generator for AWS External Anthropic (JavaScript/TypeScript)

A lightweight library for generating short-term bearer tokens for AWS External Anthropic API authentication.

Installation

npm install @aws/token-generator-for-aws-external-anthropic

Quick Start

Token duration can be customized (1 second to 12 hours). The actual token lifetime will be: min(specified duration, credentials expiry, 12 hours). Default is 12 hours.

Usage 1 — Using Default Credentials and Region

import { getTokenProvider } from "@aws/token-generator-for-aws-external-anthropic";

// Create a token provider that uses default credentials and region providers.
const provideToken = getTokenProvider();

async function example() {
  const token = await provideToken();

  // Use the token for API calls. The token has a default expiration of 12 hour.
  // If the expiresInSeconds parameter is specified during token creation, the 
  // expiration can be configured up to a maximum of 12 hours. However, the actual 
  // token validity period will always be the minimum of the requested expiration 
  // time and the AWS credentials' expiry time
  console.log(`Bearer Token: ${token}`);
}

Usage 2 — Using Custom Configuration

This example uses STS Assume Role. You can use any supported credentials provider.

import { getTokenProvider } from "@aws/token-generator-for-aws-external-anthropic";
import { fromTemporaryCredentials } from "@aws-sdk/credential-providers";

const provideToken = getTokenProvider({
  credentials: fromTemporaryCredentials({
    params: {
      RoleArn: "arn:aws:iam::123456789012:role/MyRole",
    },
  }),
  region: "us-east-1",
  expiresInSeconds: 3600,
});

async function example() {
  const token = await provideToken();
  console.log(`Bearer Token: ${token}`);
}

Usage 3 — Using Static One-Shot

Pass credentials, region, and expiry directly. No instance needed.

import { getToken } from "@aws/token-generator-for-aws-external-anthropic";

async function example() {
  const token = await getToken({
    credentials: {
      accessKeyId: "YOUR_ACCESS_KEY_ID",
      secretAccessKey: "YOUR_SECRET_ACCESS_KEY",
      sessionToken: "YOUR_SESSION_TOKEN",
    },
    region: "us-east-1",
    expiresInSeconds: 7200,
  });

  // Use the token for API calls. The token has an expiration of 2 hour. However, the actual token validity period
  // will always be the minimum of the requested expiration time and the AWS credentials' expiry time
  console.log(`Bearer Token: ${token}`);
}

API Reference

• API Reference - Detailed API documentation

Token Format

The generated token has the format:

aws-external-anthropic-api-key-<base64-encoded-payload>

The payload is a Base64-encoded SigV4 presigned URL scoped to the aws-external-anthropic service. The token can be decoded for debugging purposes but should be treated as an opaque string in production.

Requirements

• Node.js: 16.0.0 or later
• TypeScript: 4.7.0 or later (for TypeScript users)

Security Considerations

• Token Expiration: Tokens are short-lived with a maximum lifetime of 12 hours. The actual expiry is min(specified duration, credentials expiry, 12 hours). Use the shortest practical duration for your use case.
• Secure Storage: Do not log or store tokens in plain text. Treat them as sensitive credentials.
• No Embedded Credentials: No long-term credentials are embedded in the token. The token contains a SigV4 presigned URL, not the signing keys themselves.
• Credential Management: Use IAM roles or temporary credentials instead of long-term access keys where possible.
• Network Security: Always transmit tokens over HTTPS.
• Least Privilege: Scope IAM permissions to the minimum required for your use case.
• Region Scoping: Tokens are scoped to a specific AWS region and cannot be used across regions.

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

Contributing

See CONTRIBUTING for more information.

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.

Changelog

See CHANGELOG for release history.