Secrets Management API

The Secrets API provides secure encrypted storage for sensitive data like API keys, tokens, and credentials. All values are encrypted at rest and can only be accessed by admin users. Use secrets to store third-party API keys that your serverless functions need to access.

List All Secrets

Retrieve metadata for all secrets without exposing their values. Use this endpoint to list available secrets and check their status.

Authentication

Requires:

Bearer Token: Admin JWT token in Authorization: Bearer <token> header

Response

secrets

array

Array of secret metadata objects (values are not included)

secrets[].id

string

Unique UUID identifier for the secret

secrets[].key

string

Unique key identifier (uppercase with underscores, e.g., STRIPE_API_KEY)

secrets[].isActive

boolean

Whether the secret is currently active

secrets[].isReserved

boolean

Whether the secret is protected from deletion

secrets[].createdAt

string

When the secret was created (ISO 8601 format)

secrets[].updatedAt

string

When the secret was last updated (ISO 8601 format)

secrets[].expiresAt

string | null

When the secret expires (null if no expiration)

Example Request

curl -X GET https://your-app.region.insforge.app/api/secrets \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

Example Response

{
  "secrets": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "key": "STRIPE_API_KEY",
      "isActive": true,
      "isReserved": false,
      "createdAt": "2024-01-21T10:30:00Z",
      "updatedAt": "2024-01-21T10:30:00Z",
      "expiresAt": null
    },
    {
      "id": "223e4567-e89b-12d3-a456-426614174001",
      "key": "OPENAI_API_KEY",
      "isActive": true,
      "isReserved": true,
      "createdAt": "2024-01-20T09:15:00Z",
      "updatedAt": "2024-01-20T09:15:00Z",
      "expiresAt": "2025-01-20T09:15:00Z"
    }
  ]
}

Create a Secret

Create a new encrypted secret with a unique key identifier. The value will be encrypted before storage.

Authentication

Requires:

Bearer Token: Admin JWT token in Authorization: Bearer <token> header

Request Body

key

string

required

Unique key identifier. Must contain only uppercase letters, numbers, and underscores (e.g., STRIPE_API_KEY, OAUTH_CLIENT_SECRET).Pattern: ^[A-Z0-9_]+$

value

string

required

Secret value to be encrypted and stored securely

isReserved

boolean

default:"false"

Whether the secret is protected from deletion. Reserved secrets cannot be deleted via the API.

expiresAt

string

Optional expiration date for the secret (ISO 8601 format). After this date, the secret may be considered invalid.

Response

success

boolean

Whether the secret was created successfully

message

string

Success message confirming creation

string

UUID of the newly created secret

Example Request

curl -X POST https://your-app.region.insforge.app/api/secrets \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "STRIPE_API_KEY",
    "value": "sk_live_...",
    "isReserved": false
  }'

Example Response

{
  "success": true,
  "message": "Secret STRIPE_API_KEY has been created successfully",
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

Error Responses

400 Bad Request - Missing required fields:

{
  "error": "INVALID_INPUT",
  "message": "Both key and value are required",
  "statusCode": 400
}

400 Bad Request - Invalid key format:

{
  "error": "INVALID_INPUT",
  "message": "Invalid key format. Use uppercase letters, numbers, and underscores only (e.g., STRIPE_API_KEY)",
  "statusCode": 400
}

409 Conflict - Secret already exists:

{
  "error": "INVALID_INPUT",
  "message": "Secret already exists: STRIPE_API_KEY",
  "statusCode": 409
}

Get Secret Value

Retrieve the decrypted value of a specific secret by its key identifier.

Authentication

Requires:

Bearer Token: Admin JWT token in Authorization: Bearer <token> header

Path Parameters

key

string

required

Secret key identifier (e.g., STRIPE_API_KEY)Pattern: ^[A-Z0-9_]+$

Response

key

string

Secret key identifier

value

string

Decrypted secret value

Example Request

curl -X GET https://your-app.region.insforge.app/api/secrets/STRIPE_API_KEY \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

Example Response

{
  "key": "STRIPE_API_KEY",
  "value": "sk_live_..."
}

Error Responses

404 Not Found - Secret doesn’t exist:

{
  "error": "NOT_FOUND",
  "message": "Secret not found: INVALID_KEY",
  "statusCode": 404
}

Update Secret

Update an existing secret’s value or metadata. The new value will be encrypted before storage.

Authentication

Requires:

Bearer Token: Admin JWT token in Authorization: Bearer <token> header

Path Parameters

key

string

required

Secret key identifier (e.g., STRIPE_API_KEY)Pattern: ^[A-Z0-9_]+$

Request Body

value

string

New secret value (will be encrypted)

isActive

boolean

Whether the secret is active. Set to false to temporarily disable a secret without deleting it.

isReserved

boolean

Whether the secret is protected from deletion

expiresAt

string | null

Expiration date (ISO 8601 format). Set to null to remove expiration.

Response

success

boolean

Whether the update was successful

message

string

Success message confirming update

Example Request

# Update secret value
curl -X PUT https://your-app.region.insforge.app/api/secrets/STRIPE_API_KEY \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "sk_live_new_key..."
  }'

# Deactivate a secret
curl -X PUT https://your-app.region.insforge.app/api/secrets/STRIPE_API_KEY \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "isActive": false
  }'

Example Response

{
  "success": true,
  "message": "Secret STRIPE_API_KEY has been updated successfully"
}

Error Responses

404 Not Found - Secret doesn’t exist:

{
  "error": "NOT_FOUND",
  "message": "Secret not found: INVALID_KEY",
  "statusCode": 404
}

500 Internal Server Error - Update failed:

{
  "error": "INTERNAL_ERROR",
  "message": "Failed to update secret: STRIPE_API_KEY",
  "statusCode": 500
}

Delete Secret

Mark a secret as inactive (soft delete). This operation cannot be performed on reserved secrets.

Authentication

Requires:

Bearer Token: Admin JWT token in Authorization: Bearer <token> header

Path Parameters

key

string

required

Secret key identifier (e.g., STRIPE_API_KEY)Pattern: ^[A-Z0-9_]+$

Response

success

boolean

Whether the deletion was successful

message

string

Success message confirming deletion

Example Request

curl -X DELETE https://your-app.region.insforge.app/api/secrets/STRIPE_API_KEY \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

Example Response

{
  "success": true,
  "message": "Secret STRIPE_API_KEY has been deleted successfully"
}

Error Responses

403 Forbidden - Cannot delete reserved secret:

{
  "error": "FORBIDDEN",
  "message": "Cannot delete reserved secret: OPENAI_API_KEY",
  "statusCode": 403
}

404 Not Found - Secret doesn’t exist:

{
  "error": "NOT_FOUND",
  "message": "Secret not found: INVALID_KEY",
  "statusCode": 404
}

When to Use Secrets Management

Use the Secrets API to:

Store API keys: Securely store third-party service credentials (Stripe, SendGrid, etc.)
Manage tokens: Store OAuth tokens, JWT secrets, and authentication credentials
Configuration management: Store sensitive configuration that serverless functions need
Security best practices: Avoid hardcoding sensitive values in your application code
Rotation: Update expired or compromised credentials without code changes

Common Use Cases

Serverless Functions: Store API keys that your functions access via environment variables
Payment Processing: Store Stripe, PayPal, or other payment gateway credentials
Email Services: Store SendGrid, Mailgun, or SMTP credentials
OAuth Integration: Store client secrets for Google, GitHub, or other OAuth providers
Third-party APIs: Store credentials for any external service your backend integrates with

Security Best Practices

Never expose secrets: Don’t include secret values in client-side code or logs
Use reserved flag: Mark critical secrets as reserved to prevent accidental deletion
Set expiration dates: Use expiresAt for time-limited credentials
Rotate regularly: Update secret values periodically for enhanced security
Admin-only access: Only admin users can create, read, update, or delete secrets

Core APIs

Management APIs

Secrets Management API

List All Secrets

Authentication

Response

Example Request

Example Response

Create a Secret

Authentication

Request Body

Response

Example Request

Example Response

Error Responses

Get Secret Value

Authentication

Path Parameters

Response

Example Request

Example Response

Error Responses

Update Secret

Authentication

Path Parameters

Request Body

Response

Example Request

Example Response

Error Responses

Delete Secret

Authentication

Path Parameters

Response

Example Request

Example Response

Error Responses

When to Use Secrets Management

Common Use Cases

Security Best Practices

Core APIs

Management APIs

Documentation Index

​List All Secrets

​Authentication

​Response

​Example Request

​Example Response

​Create a Secret

​Authentication

​Request Body

​Response

​Example Request

​Example Response

​Error Responses

​Get Secret Value

​Authentication

​Path Parameters

​Response

​Example Request

​Example Response

​Error Responses

​Update Secret

​Authentication

​Path Parameters

​Request Body

​Response

​Example Request

​Example Response

​Error Responses

​Delete Secret

​Authentication

​Path Parameters

​Response

​Example Request

​Example Response

​Error Responses

​When to Use Secrets Management

​Common Use Cases

​Security Best Practices

List All Secrets

Authentication

Response

Example Request

Example Response

Create a Secret

Authentication

Request Body

Response

Example Request

Example Response

Error Responses

Get Secret Value

Authentication

Path Parameters

Response

Example Request

Example Response

Error Responses

Update Secret

Authentication

Path Parameters

Request Body

Response

Example Request

Example Response

Error Responses

Delete Secret

Authentication

Path Parameters

Response

Example Request

Example Response

Error Responses

When to Use Secrets Management

Common Use Cases

Security Best Practices