# Terraform provider

The OhAuthCat Terraform provider manages your OhAuthCat configuration through the management API. Every resource belongs to the environment of the API key the provider uses. The provider is the one part of OhAuthCat published as open source.

## Configure

Declare `ohauthcat/ohauthcat` ([registry.terraform.io/ohauthcat/ohauthcat](https://registry.terraform.io/providers/ohauthcat/ohauthcat)) as a required provider and add an empty `provider "ohauthcat"` block. The provider reads:

| Setting    | Default                                                                                             |
| ---------- | --------------------------------------------------------------------------------------------------- |
| `api_key`  | `OHAUTHCAT_API_KEY`; a secret key (`sk_test_…` or `sk_live_…`)                                      |
| `base_url` | `OHAUTHCAT_BASE_URL`, then `https://api.ohauthcat.com`. Must use `https`, except for loopback hosts |

Use a key with only the scopes your configuration needs, and an [organization-scoped key](/authorization/organization-api-keys/) when one workspace manages one customer.

## Resources

| Name                                              | What it manages                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ohauthcat_audit_log_schema`                      | The schema of one audit log action. Every change creates a new version; schemas cannot be deleted, so destroying it only removes it from state. Import with the action name.                                                                                                                                                                                                                                                                                                                                                                   |
| `ohauthcat_authorization_permission`              | An RBAC permission that roles can grant.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `ohauthcat_authorization_role`                    | An RBAC role, environment-wide or for one organization, with the permissions it grants.                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `ohauthcat_bot_protection`                        | Bot protection for hosted sign-in (one per environment): CAPTCHA, device tracking and rules. Destroying it only removes it from state. Import with the ID bot_protection.                                                                                                                                                                                                                                                                                                                                                                      |
| `ohauthcat_branding`                              | The environment's branding (one per environment). Destroying it clears every field except the themes, which the API cannot clear. Import with the ID branding.                                                                                                                                                                                                                                                                                                                                                                                 |
| `ohauthcat_connection`                            | An SSO connection (SAML 2.0 or OIDC) for an organization. The IdP values are write-only in the API, so Terraform detects drift only on the values the API returns. A connection must still be tested and activated (in the dashboard or setup portal) before it signs users in.                                                                                                                                                                                                                                                                |
| `ohauthcat_connection_share`                      | Shares an SSO connection with another organization for the listed routing domains. There is no update route, so every change replaces the share. Import with `<connection_id>/<share_id>`.                                                                                                                                                                                                                                                                                                                                                     |
| `ohauthcat_custom_domain`                         | A custom hostname for the setup portal, SSO broker, SCIM endpoint or email sender. Publish dns_records, then verify it. The API has no update, so every change replaces it.                                                                                                                                                                                                                                                                                                                                                                    |
| `ohauthcat_directory`                             | A SCIM directory that syncs an organization's users and groups.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `ohauthcat_directory_source`                      | Credentials and poll interval of a pulled directory (bamboohr, rippling_hris, google_admin_sdk, sftp_csv, workday, hibob, personio or gusto). The API checks the credentials, stores them sealed and starts polling. BambooHR and Google Workspace connect only by OAuth from the setup portal or dashboard, so their sources are interval-only: declare only `directory_id` and `sync_interval_minutes`. There is no delete route: destroying only removes it from state; delete the directory to stop syncing. Import with the directory ID. |
| `ohauthcat_directory_source_ssh_key`              | An Ed25519 key pair OhAuthCat generates for an sftp_csv directory; the private key is sealed and never returned. Install public_key for the SFTP user, then save the source without a private key. Replace the resource (`terraform apply -replace`) to rotate the key. Destroying it only removes it from state. Import with the directory ID.                                                                                                                                                                                                |
| `ohauthcat_encryption_key`                        | A customer-managed AWS KMS key (BYOK, Enterprise) for the environment or one organization. Creating it registers a new active key version and re-seals the scope's secrets in the background. Key versions cannot be deleted: destroying it only removes it from state (deprecate older versions from the dashboard).                                                                                                                                                                                                                          |
| `ohauthcat_environment_settings`                  | Portal and notification settings of the API key's environment (one per environment). Destroying it only removes it from state. Import with the ID environment.                                                                                                                                                                                                                                                                                                                                                                                 |
| `ohauthcat_environment_signin_host`               | The environment's active hosted sign-in host (one per environment), which is the WebAuthn relying party ID new end-user passkeys bind to. Existing passkeys keep working only on the host they were created on, so every change needs `acknowledge_passkey_reset = true`. Destroying it only removes it from state. Import with the ID signin_host.                                                                                                                                                                                            |
| `ohauthcat_feature_flag`                          | A feature flag with targeting rules.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `ohauthcat_log_stream`                            | A destination for the environment's sign-in records (Datadog, Splunk HEC, HTTPS or S3). The API has no update, so every change replaces the stream. Credentials are write-only and are not read back.                                                                                                                                                                                                                                                                                                                                          |
| `ohauthcat_m2m_client`                            | A machine-to-machine client that gets access tokens with the client credentials grant. The secret is returned only on create. Destroying it revokes the client.                                                                                                                                                                                                                                                                                                                                                                                |
| `ohauthcat_oauth_client`                          | An OAuth application (first or third party) that signs users in through OhAuthCat. A confidential client's secret is returned only on create.                                                                                                                                                                                                                                                                                                                                                                                                  |
| `ohauthcat_oauth_resource`                        | An API or MCP server protected by OhAuthCat-issued access tokens.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `ohauthcat_oauth_scope`                           | An OAuth scope your authorization server offers. Import with the scope name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `ohauthcat_organization`                          | An organization: one of your customers, whose IT admin connects their identity provider.                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `ohauthcat_organization_allowed_intents`          | The setup-portal intents one organization may use, managed on their own (do not also set allowed_intents on ohauthcat_organization). One per organization; destroying it only removes it from state. Import with the organization ID.                                                                                                                                                                                                                                                                                                          |
| `ohauthcat_organization_api_key`                  | A secret [organization-scoped API key](/authorization/organization-api-keys/). The secret is returned only on create and kept in state as sensitive. Any change, including a roll (`terraform apply -replace`), creates a new key and revokes the old one; destroying it revokes the key. Import with `<organization_id>/<key_id>` (the secret is then empty).                                                                                                                                                                                 |
| `ohauthcat_organization_domain`                   | A domain an organization claims. Publish verification_record in DNS to verify it. Import with `<organization_id>/<domain_id>`.                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `ohauthcat_organization_profile`                  | An organization's public profile: slug, logo and primary colour, used by the setup portal and hosted pages. One per organization; destroying it clears the three values. Import with the organization ID.                                                                                                                                                                                                                                                                                                                                      |
| `ohauthcat_organization_user_management_settings` | An organization's end-user sign-in overrides (Business and above): required MFA, required SSO and the allowed methods. Destroying it removes the overrides. Import with the organization ID.                                                                                                                                                                                                                                                                                                                                                   |
| `ohauthcat_portal_profile`                        | A setup-portal profile: which IdPs and features an IT admin is offered, and which attributes they must map.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `ohauthcat_role_assignment_rule`                  | A role assignment rule: users who match get role in the profile your app receives. Lower priority wins.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `ohauthcat_sign_in_hook`                          | A webhook OhAuthCat calls during sign-in or after a directory event, which can change or refuse it. The signing secret is returned only on create.                                                                                                                                                                                                                                                                                                                                                                                             |
| `ohauthcat_sign_in_policy`                        | A sign-in policy for the environment or one organization: forced SSO, session length, IdP-initiated sign-in, JIT provisioning or allow/deny expressions.                                                                                                                                                                                                                                                                                                                                                                                       |
| `ohauthcat_sign_in_risk_policy`                   | The environment's sign-in risk rule: what to do when a sign-in's risk score reaches min_score. Destroying it removes the rule. Import with the ID sign_in_risk_policy.                                                                                                                                                                                                                                                                                                                                                                         |
| `ohauthcat_ssf_stream`                            | An [SSF stream](/signals/) that sends CAEP and RISC events to your receiver by push or poll. The endpoint URL and authorization header are write-only, so changes made outside Terraform are not detected.                                                                                                                                                                                                                                                                                                                                     |
| `ohauthcat_trusted_token_issuer`                  | An external token issuer whose JWTs OhAuthCat accepts (token exchange). There is no update route, so every change replaces it.                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `ohauthcat_user_management_settings`              | How the environment's end users sign in on the hosted pages (one per environment): methods, password rules, MFA, account linking, sessions and passkey apps. Destroying it only removes it from state. Import with the ID user_management_settings.                                                                                                                                                                                                                                                                                            |
| `ohauthcat_webhook_endpoint`                      | A webhook endpoint that receives signed event deliveries.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

## Data sources

| Name                                     | What it manages                                                                                             |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `ohauthcat_authorization_permission`     | An RBAC permission that roles can grant.                                                                    |
| `ohauthcat_authorization_role`           | An RBAC role, environment-wide or for one organization, with the permissions it grants.                     |
| `ohauthcat_connection`                   | Look up an SSO connection by ID, for example to give its SP values to an IdP managed elsewhere.             |
| `ohauthcat_encryption_key`               | A customer-managed AWS KMS key (BYOK, Enterprise) for the environment or one organization.                  |
| `ohauthcat_environment`                  | The environment the provider's API key belongs to.                                                          |
| `ohauthcat_feature_flag`                 | A feature flag with targeting rules.                                                                        |
| `ohauthcat_m2m_client`                   | A machine-to-machine client that gets access tokens with the client credentials grant.                      |
| `ohauthcat_oauth_client`                 | An OAuth application (first or third party) that signs users in through OhAuthCat.                          |
| `ohauthcat_oauth_resource`               | An API or MCP server protected by OhAuthCat-issued access tokens.                                           |
| `ohauthcat_organization`                 | Look up an organization by id or by external_id.                                                            |
| `ohauthcat_organization_allowed_intents` | The setup-portal intents one organization may use.                                                          |
| `ohauthcat_organization_profile`         | An organization's public profile: slug, logo and primary colour, used by the setup portal and hosted pages. |
| `ohauthcat_sign_in_hook`                 | A webhook OhAuthCat calls during sign-in or after a directory event, which can change or refuse it.         |
| `ohauthcat_ssf_stream`                   | An [SSF stream](/signals/) that sends CAEP and RISC events to your receiver, by push or poll.               |
| `ohauthcat_user_management_settings`     | How the environment's end users sign in on the hosted pages.                                                |

## Things to know

- Secrets (client secrets, M2M and hook signing secrets, organization API key secrets) are returned only when the object is created. Store them from the Terraform output into your secret manager, and mark outputs sensitive.
- Terraform state stores those secrets in plain text. Keep state in an encrypted remote backend with access control (for example S3 with server-side encryption and locking, or HCP Terraform), never in a local file or in version control.
- A connection still has to be tested and activated in the dashboard or the setup portal before it signs users in.
- Resources with no update route (custom domains, log streams, connection shares, trusted issuers) are replaced on any change.
- A connection's `routing_domains` must be domains of its organization: create the `ohauthcat_organization_domain` first. A share's `routing_domains` must be verified by the target organization.
- Import an existing object with `terraform import`, using its ID, or the import ID each resource's documentation names. After an import, the first apply records the write-only inputs of connections, connection shares and log streams as a one-line in-place change; nothing is replaced.
- An interval-only `ohauthcat_directory_source` needs its source connected first (from the setup portal or the dashboard); until then the API answers 404. Gusto is coming soon.

Check each resource's documentation in the provider for every argument.

The provider is not yet published to the Terraform Registry; install it from a release build until it is.
