Secrets

The Secrets API provides encrypted key-value storage for sensitive configuration values such as API keys, tokens, and credentials. Secrets are scoped to organizations and encrypted at rest using AES-256.

Overview

• Encryption: AES-256 with per-value random IV, stored as base64 in PostgreSQL
• Scoping: Secrets are automatically scoped to the organization via qualified naming (org/{organizationId}/{secretName})
• Authorization: Users must be a member of the target organization
• Integration: Secrets can be referenced from Organization Configuration values for automatic resolution

GraphQL Schema

Mutations

setSecret

Creates or updates an encrypted secret for an organization.

mutation {
  setSecret(
    organizationId: Int!
    secretName: String!
    secretValue: String!
  ): SetSecretResult!
}

Response Type:

type SetSecretResult {
  secretName: String!   # Qualified name: "org/{organizationId}/{secretName}"
}

Example:

mutation {
  setSecret(
    organizationId: 42
    secretName: "CARRIER_API_KEY"
    secretValue: "sk-abc123..."
  ) {
    secretName
  }
}

Response:

{
  "data": {
    "setSecret": {
      "secretName": "org/42/CARRIER_API_KEY"
    }
  }
}

deleteSecret

Deletes a secret from the organization's secret store.

mutation {
  deleteSecret(
    organizationId: Int!
    secretName: String!
  ): Boolean!
}

Example:

mutation {
  deleteSecret(
    organizationId: 42
    secretName: "CARRIER_API_KEY"
  )
}

Response:

{
  "data": {
    "deleteSecret": true
  }
}

Validation Rules

Field	Rule
organizationId	Must be greater than 0
secretName	Must not be empty
secretValue (set only)	Must not be empty

Authorization

• The authenticated user must have access to the specified organizationId
• Returns 401 Unauthorized if the user does not belong to the target organization

Usage with Organization Config

Secrets can be referenced in organization configuration values using secret reference syntax. The OrganizationConfigService automatically resolves these references at runtime, enabling secure storage of sensitive configuration without exposing plaintext values in the configuration store.