Configuration as code with Terraform

Authsignal’s Terraform provider lets you manage your tenant’s configuration as code instead of editing it by hand in the Authsignal Portal. Use it to:

Keep your action configurations, rules, themes, and message overrides in version control.
Review configuration changes through pull requests before applying them.
Promote configuration changes between environments, for example from a staging tenant to production.

If this is your first time using Terraform, we recommend reading the official introduction to learn the fundamentals.

Get started

Create a Management API secret key

The provider authenticates using a Management API secret key, which you can generate in the Authsignal Portal.

Configure the provider

The provider needs the following 3 values, all shown on the portal page linked above. You can write them directly into your Terraform files, but we recommend supplying them as environment variables, especially for production environments.

terraform {
  required_providers {
    authsignal = {
      source  = "authsignal/authsignal"
      version = "1.0.0"
    }
  }
}

provider "authsignal" {
  host       = "https://api.authsignal.com/v1/management" # AUTHSIGNAL_HOST
  tenant_id  = "aaaa-bbbb-cccc-dddd"                      # AUTHSIGNAL_TENANT_ID
  api_secret = "<management api secret key>"              # AUTHSIGNAL_API_SECRET
}

The host value is your API host URL with /v1/management appended.

Initialize and start declaring resources

Run terraform init to validate the configuration. From here you can start declaring resources. See Working with resources below for examples, and the Terraform registry for the full list of available resources.

Adopt Terraform on an existing tenant

If your tenant already has configuration you created in the portal, you don’t need to delete it and recreate it in Terraform. Two techniques make adoption easier:

Export rule JSON from the portal. Rules are easier to build in the portal’s editor than to write by hand, so configure them there first and export the result.
Import existing resources. Use terraform import to bring resources that already exist in your tenant under Terraform management. Write the corresponding Terraform for the resource, then import it using the address syntax shown under each resource’s documentation on the Terraform registry. Import commands for each resource type are shown in Working with resources below.

Exporting rule JSON from the portal

After configuring a rule in the portal, you can export the rule’s JSON:

Click 'Edit'

A screenshot showing where the edit rule button
is

Click 'Export'

A screenshot showing the export rule json button
is

You will need to edit the exported JSON slightly to conform to valid Terraform syntax. See the rule resource docs for the correct structure and field names.

Working with resources

The sections below cover the most common resources. The Terraform registry is the source of truth for the full list of resources and their attributes.

Action configurations

resource "authsignal_action_configuration" "my_action" {
  action_code                = "My-Action"
  default_user_action_result = "ALLOW"
}

To import an existing action configuration, you will need your action code, which you can find in the portal:

A screenshot showing where to find an action's code in the
portal

terraform import authsignal_action_configuration.my_action My-Action

Rules

resource "authsignal_rule" "my_rule" {
  action_code = authsignal_action_configuration.my_action.action_code
  name        = "My-Rule"
  is_active   = true
  priority    = 0
  type        = "CHALLENGE"
  conditions = jsonencode({
    "and" : [
      {
        "==" : [
          {
            "var" : "ip.isAnonymous"
          },
          true
        ]
      }
    ]
  })
}

To import an existing rule, you will need its unique identifier, which you can find in the URL when editing the rule in the portal:

A screenshot showing where to find a rule's unique identifier in the
portal

The import ID combines the action code and the rule’s identifier:

terraform import authsignal_rule.my_rule "My-Action/ccad3b11-14dc-4509-895a-dacac4983ed3"

Themes

Themes control the branding of the pre-built UI. A tenant has a single theme, and every tenant starts with default theme settings, so import the existing theme before managing it with Terraform.

resource "authsignal_theme" "my_theme" {
  name          = "My Tenant"
  logo_url      = "<url to an image>"
  favicon_url   = "<url to an image>"
  watermark_url = "<url to an image>"
  primary_color = "#ABCD12"
  borders = {
    button_border_radius = 1
    card_border_radius   = 3
    input_border_radius  = 5
  }
  colors = {
    card_background      = "#ABCD12"
    container_background = "#ABCD12"
    body_text            = "#ABCD12"
  }
}

This example shows a subset of the available attributes. See the theme resource docs for the full schema, including colors, borders, page background, and container layout settings. Because the theme is a tenant-wide singleton, import it using an empty string as the resource ID:

terraform import authsignal_theme.my_theme ""

Message overrides

Message overrides let you replace the default copy shown in the pre-built UI, per locale. If the tenant doesn’t have any overrides yet, you can declare the resource and apply it directly. If overrides already exist (for example, configured in the portal), import them first so the plan shows what will change. Otherwise the apply is rejected to avoid silently overwriting them. The overrides attribute is a map keyed by locale, then by message override ID (e.g. sms-code-entry.heading). Applying is a full replacement: any override not present is removed, and omitting overrides clears them all.

resource "authsignal_message_overrides" "my_message_overrides" {
  overrides = {
    en = {
      "sms-code-entry.heading" = "Enter your code"
    }
    "pt-br" = {
      "sms-code-entry.heading" = "Insira seu código"
    }
  }
}

To discover the valid override IDs, locales, and default copy, use the authsignal_message_overrides_catalog data source:

data "authsignal_message_overrides_catalog" "catalog" {}

To read the tenant’s currently configured overrides, use the authsignal_message_overrides data source:

data "authsignal_message_overrides" "current" {}

Message overrides are a tenant-wide singleton, imported from the "" ID:

terraform import authsignal_message_overrides.my_message_overrides ""

Getting started

Integrations

Authentication methods

Implementation options

Actions & rules

Users

Advanced usage

Configuration as code with Terraform

Get started

Adopt Terraform on an existing tenant

Exporting rule JSON from the portal

Working with resources

Action configurations

Rules

Themes

Message overrides

​Get started

​Adopt Terraform on an existing tenant

​Exporting rule JSON from the portal

​Working with resources

​Action configurations

​Rules

​Themes

​Message overrides

Get started

Adopt Terraform on an existing tenant

Exporting rule JSON from the portal

Working with resources

Action configurations

Rules

Themes

Message overrides