Tools & integrations

Terraform provider

A Terraform Plugin Framework provider that manages generic secrets, named variables, containers, access grants and stored OIDC client metadata through the SecretServer REST API.

The provider is not yet published to the Terraform Registry or as a public download. This page documents its configuration and behavior; its source address is afterdark/secretserver.

Configure

terraform {
  required_providers {
    secretserver = {
      source  = "afterdark/secretserver"
      version = "~> 1.0"
    }
  }
}

provider "secretserver" {
  api_url = "https://api.secretserver.io"   # or SS_API_URL; /api/v1 may be included
  api_key = var.secretserver_api_key       # or SS_API_KEY
}

Explicit attributes override SS_API_URL and SS_API_KEY. The URL defaults to https://api.secretserver.io; the API key is required. Use a scoped API key with only the permissions the managed resources need.

Resources, data sources and ephemeral resources

Type	Name	Purpose	Scopes
Resource	`secretserver_secret`	Generic secret. Use exactly one of value or value_wo.	secrets:read, write, delete
Resource	`secretserver_container`	Container with name, slug and description	containers:read, write
Resource	`secretserver_share`	Access grant to exactly one user or group, read or manage, optional RFC3339 expires_at	sharing:manage
Resource	`secretserver_variable`	Named variable mapping; stores metadata only	variables:read, write
Resource	`secretserver_oidc_client`	Stored OIDC client metadata; does not register or rotate at the identity provider	oidc:read, write
Data source	`secretserver_secret`	Read by container and key, or by name	read access to the secret
Data source	`secretserver_secret_version`	Read a historical version by container, key and version	read access to the secret
Data source	`secretserver_oidc_client`	Read OIDC metadata by id, without the client secret	oidc:read
Ephemeral	`secretserver_secret`	Read a secret by name without storing it in state	read access to the secret
Ephemeral	`secretserver_template`	Resolve a %%NAME%% template without storing it in state	read access to each referenced credential

Example

resource "secretserver_container" "prod" {
  name = "Production"
  slug = "prod"
}

resource "secretserver_secret" "db" {
  name             = "database-password"
  container_id     = secretserver_container.prod.id
  value_wo         = var.database_password
  value_wo_version = 1
}

resource "secretserver_share" "reader" {
  secret_type         = "secret"
  secret_id           = secretserver_secret.db.id
  shared_with_user_id = var.reader_user_id
  permission          = "read"
}

Keep values out of state

Ordinary value and data source results are marked sensitive but persist in state. Write-only value_wo needs Terraform 1.11 or newer; increment value_wo_version to change it. Terraform cannot detect remote drift of a write-only value. Ephemeral resources need Terraform 1.10 or newer and can feed write-only arguments:

ephemeral "secretserver_secret" "source" {
  name = "source-password"
}

resource "secretserver_secret" "copy" {
  name             = "copied-password"
  value_wo         = ephemeral.secretserver_secret.source.value
  value_wo_version = 1
}

Import

terraform import secretserver_secret.db database-password
terraform import secretserver_container.prod CONTAINER_UUID
terraform import secretserver_share.reader secret/SECRET_UUID/SHARE_UUID
terraform import secretserver_variable.sudo LOG_SERVER_TX1_S
terraform import secretserver_oidc_client.app OIDC_RECORD_UUID

Limits

Secret names and container slugs are immutable; changing them replaces the resource.
Any change to an access grant revokes it and creates a new one.
OIDC reads do not return client_secret, so it must be supplied on import, stays in state, and its remote drift cannot be detected. rotate_secret = true is rejected: rotate at the issuer, then update client_secret.
Requests use a 30 second timeout, do not follow redirects and cap responses at 4 MiB.

Named variables →API reference →