Skip to main content
Neptune Secrets provide secure storage for API keys, tokens, and other sensitive configuration. Secrets are stored in AWS Secrets Manager and accessed at runtime using the AWS SDK.

Quick Start

Ask your AI assistant:
“Add a secret called STRIPE_API_KEY to my project”
Or add it directly to your neptune.json:
neptune.json
After provisioning, set the secret value:
“Set my STRIPE_API_KEY secret”
Your AI assistant will prompt you securely for the value.

How It Works

When you provision a secret, Neptune:
  1. Creates an AWS Secrets Manager secret with a physical name (e.g., neptune-abc123-STRIPE_API_KEY) for global uniqueness
  2. Configures all necessary IAM permissions so your running service can access it
  3. Returns the physical secret name to your AI assistant
The physical secret name is different from the logical name you define in neptune.json. For example, if you name your secret STRIPE_API_KEY, the actual AWS secret might be called neptune-abc123-STRIPE_API_KEY.

Getting the Secret Name

After provisioning, your AI assistant knows the physical secret name. Ask:
“What’s the secret name for STRIPE_API_KEY?”
Or check the deployment status:

Using Secrets in Your Application

All permissions are pre-configured, so you can use boto3 (or other AWS SDKs) to retrieve secrets without any credential configuration.
Your AI assistant knows the physical secret name after provisioning and can write the code for you with the correct secret name already filled in.

Setting Secret Values

When you ask your AI assistant to set a secret, it will prompt you to enter the value securely. The value is never displayed or logged.
“Set my STRIPE_API_KEY secret”
AI Assistant: I’ll set the STRIPE_API_KEY secret. Please provide the value when prompted. You enter the value securely AI Assistant: Secret ‘STRIPE_API_KEY’ has been set. Redeploy your application to use the new value.
After setting or updating a secret, you need to redeploy your application for the changes to take effect.

Configuration Options

Common Use Cases

If you’re using an external database service (not a Neptune Database resource):
If you’re using a Neptune-managed database, see Databases and read DATABASE_URL_<NAME> from the environment instead.

Caching Secrets

For better performance, cache secret values rather than fetching them on every request:

Updating Secrets

To update a secret value, ask your AI assistant:
“Update my STRIPE_API_KEY secret”
The new value takes effect after your next deployment.

Security

  • Encryption: Secrets are encrypted at rest using AWS Secrets Manager
  • No logging: Values are never logged or displayed
  • Isolation: Secrets are scoped to your project only
  • IAM permissions: Your service has automatic access to its own secrets
Never commit secrets to your repository. Always use Neptune Secrets for sensitive values.

Local Development

For local development, you have a few options: Option 1: Use environment variables locally Create a .env file (and add it to .gitignore):
.env
Then modify your code to check for local env vars first:
Option 2: Use AWS credentials locally If you have AWS credentials configured locally, you can access the actual Neptune secrets during development.
Many frameworks like Next.js, Vite, and Remix automatically load .env files in development, making Option 1 convenient for local testing.