---
page_title: "ona_secret Resource - ona"
subcategory: "Security and Secrets"
description: |-
  Ona secret. The plaintext value is write-only and is never stored in Terraform plan or state. Rotate a secret by changing both value and value_version.
---

# ona_secret (Resource)

Ona secret. The plaintext `value` is write-only and is never stored in Terraform plan or state. Rotate a secret by changing both `value` and `value_version`.

For product context, see [How secrets work](https://ona.com/docs/ona/configuration/secrets/overview), [Organization secrets](https://ona.com/docs/ona/organizations/organization-secrets), [Project secrets](https://ona.com/docs/ona/projects/project-secrets), and [User secrets](https://ona.com/docs/ona/configuration/secrets/user-secrets).

## Example Usage

```terraform
variable "secret_value" {
  type      = string
  sensitive = true
}

resource "ona_secret" "organization_api_key" {
  scope = "organization"
  name  = "THIRD_PARTY_API_KEY"

  value         = var.secret_value
  value_version = "2026-07-10"

  environment_variable = true
}

variable "registry_username" {
  type = string
}

variable "registry_password" {
  type      = string
  sensitive = true
}

resource "ona_secret" "registry" {
  scope      = "project"
  project_id = ona_project.api.id
  name       = "PRIVATE_REGISTRY_AUTH"

  value         = base64encode("${var.registry_username}:${var.registry_password}")
  value_version = "2026-07-10"

  container_registry_basic_auth_host = "registry.example.com"
}

resource "ona_secret" "automation_token" {
  scope              = "service_account"
  service_account_id = ona_service_account.terraform.id
  name               = "AUTOMATION_TOKEN"

  value         = var.secret_value
  value_version = "2026-07-10"

  environment_variable = true
}
```

<!-- schema generated by tfplugindocs -->
## Schema

### Required

- `name` (String) Secret name. Must be 3 to 127 characters and contain only letters, digits, and underscores.
- `scope` (String) Secret scope. Supported values are `organization`, `project`, `user`, and `service_account`.

### Optional

> **NOTE**: [Write-only arguments](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments) are supported in Terraform 1.11 and later.

- `api_only` (Boolean) Set to `true` for a secret available only to API/programmatic consumers. It is not automatically injected into environments. This is one of the mutually exclusive mount modes.
- `container_registry_basic_auth_host` (String) Container registry host for Docker basic authentication. The `value` should match the Ona API payload; use `base64encode("${var.registry_username}:${var.registry_password}")` for username/password credentials.
- `credential_proxy` (Block List) Credential proxy injection settings. Set no more than one block. Changes require replacement. (see [below for nested schema](#nestedblock--credential_proxy))
- `environment_variable` (Boolean) Set to `true` to mount this secret as an environment variable named after `name`. This is one of the mutually exclusive mount modes.
- `file_path` (String) Absolute file path where the secret is mounted. This is one of the mutually exclusive mount modes.
- `project_id` (String) Project ID. Required when `scope` is `project`.
- `service_account_id` (String) Service account ID. Required when `scope` is `service_account`.
- `user_id` (String) User ID. When `scope` is `user` and this is omitted, Ona infers the authenticated user identity.
- `value` (String, Sensitive, [Write-only](https://developer.hashicorp.com/terraform/language/resources/ephemeral#write-only-arguments)) Plaintext secret value. This write-only value is sent to Ona but is not stored in Terraform plan or state. Required on create and when changing `value_version`.
- `value_version` (String) User-managed rotation marker for resubmitting `value`. Changing `value` alone does not rotate the secret; change this marker with the value.

### Read-Only

- `created_at` (String) Time when the secret was created.
- `creator` (Attributes) Identity that created the secret. (see [below for nested schema](#nestedatt--creator))
- `id` (String) Secret ID.

<a id="nestedblock--credential_proxy"></a>
### Nested Schema for `credential_proxy`

Required:

- `header` (String) HTTP header name to inject.
- `target_hosts` (Set of String) Target hosts to intercept, such as `github.com` or `*.github.com`. Empty entries are ignored when constructing the API request.


<a id="nestedatt--creator"></a>
### Nested Schema for `creator`

Read-Only:

- `id` (String) Creator subject ID.
- `principal` (String) Creator principal type.

## Import

Import is supported using the following syntax:

The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example:

```shell
#!/usr/bin/env sh

terraform import ona_secret.organization_api_key organization/01980ed3-a090-7b5b-a74c-9bf5d8cfe53c
terraform import ona_secret.project_api_key project/01980ed3-a090-7b5b-a74c-9bf5d8cfe53c/01980ed3-a090-7b5b-a74c-9bf5d8cfe53d
terraform import ona_secret.user_api_key user/01980ed3-a090-7b5b-a74c-9bf5d8cfe53e/01980ed3-a090-7b5b-a74c-9bf5d8cfe53f
terraform import ona_secret.service_account_api_key service_account/01980ed3-a090-7b5b-a74c-9bf5d8cfe540/01980ed3-a090-7b5b-a74c-9bf5d8cfe541
```