> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neptune.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets

> Securely store API keys and sensitive configuration

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`:

```json neptune.json theme={"dark"}
{
  "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

> [!NOTE]
>
> 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:

```json theme={"dark"}
{
  "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.

> [tab] Python
>
> ```python theme={"dark"}
>     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
> ```

> [tab] Node.js
>
> ```typescript theme={"dark"}
> import { SecretsManagerClient, GetSecretValueCommand } from '@aws-sdk/client-secrets-manager';
> import Stripe from 'stripe';
>
> // Your AI assistant will provide this physical secret name
> const SECRET_NAME = 'neptune-abc123-STRIPE_API_KEY';
>
> // No credentials needed - permissions are pre-configured
> const sm = new SecretsManagerClient({ region: 'eu-west-2' });
>
> const response = await sm.send(new GetSecretValueCommand({
>   SecretId: SECRET_NAME,
> }));
>
> const stripe = new Stripe(response.SecretString!);
> ```

> [tab] Rust
>
> ```rust theme={"dark"}
> use aws_sdk_secretsmanager::Client;
>
> // Your AI assistant will provide this physical secret name
> let secret_name = "neptune-abc123-STRIPE_API_KEY";
>
> // Load config from environment (credentials pre-configured)
> let config = aws_config::load_from_env().await;
> let client = Client::new(&config);
>
> let response = client
>     .get_secret_value()
>     .secret_id(secret_name)
>     .send()
>     .await?;
>
> let secret_value = response.secret_string().unwrap();
> ```

> [!TIP]
>
> 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.

> [!NOTE]
>
> After setting or updating a secret, you need to redeploy your application for the changes to take effect.

## Configuration Options

```json theme={"dark"}
{
  "kind": "Secret",
  "name": "API_KEY"
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `kind` | string | Yes | Must be `"Secret"` |
| `name` | string | Yes | Logical name for this secret (Neptune generates a unique physical name) |

## Common Use Cases

> [accordion] Payment providers
>
> ```python theme={"dark"}
> 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']
> ```

> [accordion] Email services
>
> ```python theme={"dark"}
> 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'])
> ```

> [accordion] AI APIs
>
> ```python theme={"dark"}
> 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'])
> ```

> [accordion] External database (non-Neptune)
>
> If you're using an external database service (not a Neptune `Database` resource):
>
> ```python theme={"dark"}
> 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'])
> ```
>
> If you're using a Neptune-managed database, see [Databases](https://docs.neptune.dev/resources/databases.md) and read `DATABASE_URL_<NAME>` from the environment instead.

## Caching Secrets

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

```python theme={"dark"}
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

> [!WARNING]
>
> 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`):

```bash .env theme={"dark"}
STRIPE_API_KEY=sk_test_...
RESEND_API_KEY=re_...
OPENAI_API_KEY=sk-...
```

Then modify your code to check for local env vars first:

```python theme={"dark"}
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.

> [!TIP]
>
> Many frameworks like Next.js, Vite, and Remix automatically load `.env` files in development, making Option 1 convenient for local testing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.