Skip to main content
Amazon Nova Act supports two authentication methods: API key authentication for development and experimentation, and IAM-based authentication for production deployments.

​
API key authentication

When using API key authentication, access and use are subject to the nova.amazon.com Terms of Use.
API key authentication is the quickest way to get started with Nova Act. It’s ideal for:
  • Local development and testing
  • Experimenting with Nova Act features
  • Prototyping workflows
  • Previewing new Nova Act model versions

​
Get your API key

1

Visit the Nova Act playground

Navigate to nova.amazon.com/act and sign in
2

Generate an API key

Generate a new API key from your account settings
3

Set the environment variable

Save your API key as an environment variable:
export NOVA_ACT_API_KEY="your_api_key"

​
Use the API key in your code

Once the environment variable is set, you can use Nova Act without additional configuration: 
from nova_act import NovaAct

# API key is automatically read from NOVA_ACT_API_KEY environment variable
with NovaAct(starting_page="https://example.com") as nova:
    nova.act("Search for products")
Alternatively, pass the API key directly to the constructor: 
from nova_act import NovaAct

with NovaAct(
    starting_page="https://example.com",
    nova_act_api_key="your_api_key"
) as nova:
    nova.act("Search for products")
Never commit API keys to version control. Use environment variables or secure secret management systems.

​
IAM-based authentication

When using IAM authentication and deploying to the Nova Act AWS service, your AWS Service Terms and/or Customer Agreement apply.
IAM-based authentication is recommended for production deployments. It provides:
  • Integration with AWS Identity and Access Management
  • Fine-grained access control
  • Audit logging via CloudTrail
  • No API key management overhead

​
Prerequisites

  • AWS account with Nova Act service access
  • Configured AWS credentials (via AWS CLI, environment variables, or IAM role)
  • Permissions to create and manage Nova Act workflow definitions

​
Use IAM authentication with Workflows

IAM authentication is used automatically when you create a Workflow: 
from nova_act import NovaAct, Workflow

with Workflow(
    workflow_definition_name="my-workflow",
    model_id="nova-act-latest"
) as workflow:
    with NovaAct(
        starting_page="https://example.com",
        workflow=workflow
    ) as nova:
        nova.act("Complete the task")
The SDK will automatically use your configured AWS credentials. If you don’t have AWS credentials configured, the SDK will look for:
  1. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
  2. AWS credentials file (~/.aws/credentials)
  3. IAM role (when running on EC2, ECS, or Lambda)

​
Configure AWS credentials

Configure credentials using the AWS CLI:
aws configure
Enter your:
  • AWS Access Key ID
  • AWS Secret Access Key
  • Default region (e.g., us-east-1)
  • Default output format

​
Default boto session

The SDK will instantiate a default boto3 session if AWS credentials are already configured in your environment.
If you don’t provide boto_session_kwargs and don’t use an API key, the workflow will automatically load AWS credentials using boto3’s default credential chain. See boto3 documentation for details.

​
Authentication decision guide

Choose your authentication method based on your use case:
ScenarioRecommended Authentication
Local developmentAPI key
Testing and prototypingAPI key
Production workflowsIAM
AWS-hosted applicationsIAM
CI/CD pipelinesIAM
Sharing with teamIAM (with proper IAM policies)

​
Required permissions

For IAM-based authentication, your IAM user or role needs the following permissions: 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "nova-act:CreateWorkflowDefinition",
        "nova-act:GetWorkflowDefinition",
        "nova-act:CreateWorkflowRun",
        "nova-act:UpdateWorkflowRun",
        "nova-act:CreateSession",
        "nova-act:CreateAct",
        "nova-act:InvokeActStep",
        "nova-act:UpdateAct"
      ],
      "Resource": "*"
    }
  ]
}
For deployment to AWS AgentCore Runtime, see the deployment guide for additional required permissions.

​
Troubleshooting

Verify that:
  • The API key is correctly set in the NOVA_ACT_API_KEY environment variable
  • The API key hasn’t expired
  • You’re connected to the internet
  • The nova.amazon.com service is accessible from your location
Check that:
  • AWS credentials are properly configured (run aws sts get-caller-identity to test)
  • Your IAM user/role has the required Nova Act permissions
  • The region is set correctly (Nova Act is available in specific regions)
  • Your AWS credentials haven’t expired
  • Use API key for quick development and testing
  • Use IAM for production deployments and AWS-integrated applications
  • You can switch between authentication methods without changing your code (just use or omit the workflow parameter)

​
Next steps

Quickstart

Build your first Nova Act workflow

Workflows

Learn about workflow orchestration

Deployment

Deploy workflows to AWS

Security

Security best practices

Build docs developers (and LLMs) love

Get started for freeTalk to us