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
{
  "kind": "Service",
  "name": "my-app",
  "resources": [
    {
      "kind": "Secret",
      "name": "STRIPE_API_KEY"
    }
  ]
}
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: 
{
  "kind": "Secret",
  "name": "STRIPE_API_KEY",
  "status": "Available",
  "aws_id": "neptune-abc123-STRIPE_API_KEY"  // This is your physical secret name
}

​
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.
  • Python
  • Node.js
  • Rust
    import boto3
    import json
    
    # Your AI assistant will provide this physical secret name
    SECRET_NAME = "neptune-abc123-STRIPE_API_KEY"
    
    sm = boto3.client("secretsmanager")
    response = sm.get_secret_value(SecretId=SECRET_NAME)
    secret_value = response['SecretString']
    
    # Use the secret
    import stripe
    stripe.api_key = secret_value
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

{
  "kind": "Secret",
  "name": "API_KEY"
}
FieldTypeRequiredDescription
kindstringYesMust be "Secret"
namestringYesLogical name for this secret (Neptune generates a unique physical name)

​
Common Use Cases

import boto3
import stripe

SECRET_NAME = "neptune-abc123-STRIPE_SECRET_KEY"  # from your AI assistant

sm = boto3.client("secretsmanager")
response = sm.get_secret_value(SecretId=SECRET_NAME)
stripe.api_key = response['SecretString']

import boto3
from resend import Resend

SECRET_NAME = "neptune-abc123-RESEND_API_KEY"  # from your AI assistant

sm = boto3.client("secretsmanager")
response = sm.get_secret_value(SecretId=SECRET_NAME)
resend = Resend(api_key=response['SecretString'])

import boto3
from openai import OpenAI

SECRET_NAME = "neptune-abc123-OPENAI_API_KEY"  # from your AI assistant

sm = boto3.client("secretsmanager")
response = sm.get_secret_value(SecretId=SECRET_NAME)
openai = OpenAI(api_key=response['SecretString'])
If you’re using an external database service:
import boto3
import psycopg2

SECRET_NAME = "neptune-abc123-DATABASE_URL"  # from your AI assistant

sm = boto3.client("secretsmanager")
response = sm.get_secret_value(SecretId=SECRET_NAME)
conn = psycopg2.connect(response['SecretString'])

​
Caching Secrets

For better performance, cache secret values rather than fetching them on every request: 
import boto3
from functools import lru_cache

sm = boto3.client("secretsmanager")

@lru_cache(maxsize=None)
def get_secret(secret_name: str) -> str:
    """Fetch and cache a secret value."""
    response = sm.get_secret_value(SecretId=secret_name)
    return response['SecretString']

# Use cached value
stripe_key = get_secret("neptune-abc123-STRIPE_API_KEY")

​
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
STRIPE_API_KEY=sk_test_...
RESEND_API_KEY=re_...
OPENAI_API_KEY=sk-...
Then modify your code to check for local env vars first: 
import os
import boto3

def get_secret(secret_name: str, local_env_var: str = None) -> str:
    """Get secret from env var (local) or AWS Secrets Manager (deployed)."""
    if local_env_var and os.environ.get(local_env_var):
        return os.environ[local_env_var]
    
    sm = boto3.client("secretsmanager")
    response = sm.get_secret_value(SecretId=secret_name)
    return response['SecretString']

# Usage
stripe_key = get_secret("neptune-abc123-STRIPE_API_KEY", "STRIPE_API_KEY")
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.