Secrets

Manage app secrets via API

Secrets are encrypted environment variables that can be used in your app's spicepod configuration. They are stored securely and never exposed in plain text through the API.

List Secrets

GET https://api.spice.ai/v1/apps/{appId}/secrets

Returns a list of secrets for the specified app. Secret values are always masked.

Required scope: secrets:read

Path Parameters

Parameter

Type

Description

appId

integer

The app ID

Response

{
  "secrets": [
    {
      "id": 789,
      "name": "DATABASE_URL",
      "value": "**********",
      "created_at": "2024-01-15T10:00:00.000Z",
      "updated_at": "2024-01-15T10:00:00.000Z"
    },
    {
      "id": 790,
      "name": "API_KEY",
      "value": "**********",
      "created_at": "2024-01-15T11:00:00.000Z",
      "updated_at": "2024-01-15T11:00:00.000Z"
    }
  ]
}

Response Fields:

Field

Type

Description

id

integer

Unique secret identifier

name

string

Secret name (environment variable name)

value

string

Always masked with asterisks

created_at

string

ISO 8601 timestamp when secret was created

updated_at

string

ISO 8601 timestamp when secret was last updated

Example

curl -H "Authorization: Bearer <token>" \
  https://api.spice.ai/v1/apps/123/secrets

Get Secret

GET https://api.spice.ai/v1/apps/{appId}/secrets/{secretName}

Returns a specific secret by name. The value is always masked.

Required scope: secrets:read

Path Parameters

Parameter

Type

Description

appId

integer

The app ID

secretName

string

The secret name

Response

{
  "id": 789,
  "name": "DATABASE_URL",
  "value": "**********",
  "created_at": "2024-01-15T10:00:00.000Z",
  "updated_at": "2024-01-15T10:00:00.000Z"
}

Example

curl -H "Authorization: Bearer <token>" \
  https://api.spice.ai/v1/apps/123/secrets/DATABASE_URL

Create or Update Secret

POST https://api.spice.ai/v1/apps/{appId}/secrets

Creates a new secret or updates an existing one with the same name. This is an upsert operation.

Required scope: secrets:write

Path Parameters

Parameter

Type

Description

appId

integer

The app ID

Request Body

{
  "name": "DATABASE_URL",
  "value": "postgresql://user:pass@host:5432/db"
}

Request Fields:

Field

Type

Required

Description

name

string

Yes

Secret name (must start with letter or underscore, alphanumeric and underscores only)

value

string

Yes

Secret value (will be encrypted)

Response

{
  "id": 789,
  "name": "DATABASE_URL",
  "value": "**********",
  "created_at": "2024-01-15T10:00:00.000Z",
  "updated_at": "2024-01-15T10:00:00.000Z"
}

Returns the created or updated secret with the value masked.

Examples

Create a database connection string:

curl -X POST https://api.spice.ai/v1/apps/123/secrets \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "DATABASE_URL",
    "value": "postgresql://user:pass@localhost:5432/mydb"
  }'

Create an API key:

curl -X POST https://api.spice.ai/v1/apps/123/secrets \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OPENAI_API_KEY",
    "value": "sk-..."
  }'

Update an existing secret:

# Same endpoint - will update if name exists
curl -X POST https://api.spice.ai/v1/apps/123/secrets \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "DATABASE_URL",
    "value": "postgresql://user:newpass@localhost:5432/mydb"
  }'

Python:

import requests

# Create secret
response = requests.post(
    f"https://api.spice.ai/v1/apps/{app_id}/secrets",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json"
    },
    json={
        "name": "AWS_ACCESS_KEY_ID",
        "value": "AKIAIOSFODNN7EXAMPLE"
    }
)

secret = response.json()
print(f"Secret {secret['name']} created")

Node.js:

const response = await fetch(
  `https://api.spice.ai/v1/apps/${appId}/secrets`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'S3_SECRET_ACCESS_KEY',
      value: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY'
    })
  }
);

const secret = await response.json();
console.log(`Secret ${secret.name} created`);

Delete Secret

DELETE https://api.spice.ai/v1/apps/{appId}/secrets/{secretName}

Deletes a secret by name.

Required scope: secrets:write

Path Parameters

Parameter

Type

Description

appId

integer

The app ID

secretName

string

The secret name

Response

Secret deleted successfully. No response body.

Example

curl -X DELETE https://api.spice.ai/v1/apps/123/secrets/DATABASE_URL \
  -H "Authorization: Bearer <token>"

Deleting a secret cannot be undone. If your app depends on this secret, it may fail until you create a new one.

Using Secrets in Spicepods

Secrets are automatically available as environment variables in your Spice runtime. Reference them using the standard ${} or env: syntax:

Example Spicepod with Secrets

version: v1beta1
kind: Spicepod
name: my-app

datasets:
  - name: sales_data
    from: s3://my-bucket/sales.parquet
    params:
      region: us-east-1
      access_key_id: ${AWS_ACCESS_KEY_ID}  # From secret
      secret_access_key: env:AWS_SECRET_ACCESS_KEY  # From secret

  - name: customers
    from: postgres:public.customers
    params:
      pg_host: localhost
      pg_port: 5432
      connection_string: env:DATABASE_URL  # From secret

models:
  - name: gpt-4
    from: openai:gpt-4
    params:
      openai_api_key: ${OPENAI_API_KEY}  # From secret

Secret Naming Conventions

Valid secret names:

Must start with a letter (a-z, A-Z) or underscore (_)
Can contain letters, numbers, and underscores
Typically use UPPER_SNAKE_CASE for environment variables

Examples:

✅ DATABASE_URL
✅ AWS_ACCESS_KEY_ID
✅ _internal_api_key
✅ stripe_api_key_v2
❌ 123-invalid (starts with number)
❌ my-secret (contains hyphen)
❌ api.key (contains dot)

Security Best Practices

Secret Management

Rotate Regularly - Update secrets periodically, especially for production apps
Least Privilege - Only grant secrets:write scope to trusted automation
Never Log - Ensure secrets are not logged or printed in your application
Audit Access - Monitor who creates/updates secrets using the Management API

Storage and Transmission

Secrets are encrypted at rest in the database using AES-256
Secrets are encrypted in transit using TLS 1.3
Secrets are never returned in plain text through the API
Secret values are only available to the Spice runtime

Development vs Production

# Development secrets (staging/test)
curl -X POST https://api.spice.ai/v1/apps/123/secrets \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "DATABASE_URL",
    "value": "postgresql://localhost:5432/dev_db"
  }'

# Production secrets (separate app)
curl -X POST https://api.spice.ai/v1/apps/456/secrets \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "DATABASE_URL",
    "value": "postgresql://prod-host:5432/prod_db"
  }'

Common Secrets

Cloud Providers

AWS:

{
  "name": "AWS_ACCESS_KEY_ID",
  "value": "AKIAIOSFODNN7EXAMPLE"
}
{
  "name": "AWS_SECRET_ACCESS_KEY",
  "value": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}
{
  "name": "AWS_REGION",
  "value": "us-east-1"
}

Azure:

{
  "name": "AZURE_STORAGE_ACCOUNT_NAME",
  "value": "myaccount"
}
{
  "name": "AZURE_STORAGE_ACCESS_KEY",
  "value": "key123..."
}

GCP:

{
  "name": "GOOGLE_APPLICATION_CREDENTIALS",
  "value": "{\"type\":\"service_account\",...}"
}

Databases

PostgreSQL:

{
  "name": "DATABASE_URL",
  "value": "postgresql://user:password@host:5432/database"
}

MySQL:

{
  "name": "MYSQL_CONNECTION_STRING",
  "value": "mysql://user:password@host:3306/database"
}

AI/ML Services

OpenAI:

{
  "name": "OPENAI_API_KEY",
  "value": "sk-..."
}

Anthropic:

{
  "name": "ANTHROPIC_API_KEY",
  "value": "sk-ant-..."
}

Bulk Operations

Bulk create secrets:

import requests

secrets = {
    "AWS_ACCESS_KEY_ID": "AKIAIOSFODNN7EXAMPLE",
    "AWS_SECRET_ACCESS_KEY": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "DATABASE_URL": "postgresql://localhost:5432/mydb",
    "OPENAI_API_KEY": "sk-..."
}

for name, value in secrets.items():
    response = requests.post(
        f"https://api.spice.ai/v1/apps/{app_id}/secrets",
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json"
        },
        json={"name": name, "value": value}
    )
    if response.status_code == 200:
        print(f"✓ Created {name}")
    else:
        print(f"✗ Failed to create {name}: {response.json()}")

Terraform

Use the spiceai_secret resource to manage secrets. See Terraform Provider for full documentation.

resource "spiceai_secret" "database_password" {
  app_id = spiceai_app.example.id
  name   = "DATABASE_PASSWORD"
  value  = var.database_password
}

hashtagList Secrets

hashtagPath Parameters

hashtagResponse

hashtagExample

hashtagGet Secret

hashtagPath Parameters

hashtagResponse

hashtagExample

hashtagCreate or Update Secret

hashtagPath Parameters

hashtagRequest Body

hashtagResponse

hashtagExamples

hashtagDelete Secret

hashtagPath Parameters

hashtagResponse

hashtagExample

hashtagUsing Secrets in Spicepods

hashtagExample Spicepod with Secrets

hashtagSecret Naming Conventions

hashtagSecurity Best Practices

hashtagSecret Management

hashtagStorage and Transmission

hashtagDevelopment vs Production

hashtagCommon Secrets

hashtagCloud Providers

hashtagDatabases

hashtagAI/ML Services

hashtagBulk Operations

hashtagTerraform

List Secrets

Path Parameters

Response

Example

Get Secret

Path Parameters

Response

Example

Create or Update Secret

Path Parameters

Request Body

Response

Examples

Delete Secret

Path Parameters

Response

Example

Using Secrets in Spicepods

Example Spicepod with Secrets

Secret Naming Conventions

Security Best Practices

Secret Management

Storage and Transmission

Development vs Production

Common Secrets

Cloud Providers

Databases

AI/ML Services

Bulk Operations

Terraform