Admin SAML IdP Certificates API

This topic provides reference information for the /admin/saml-settings/idp-certificates endpoints, which manage the SAML identity provider (IdP) certificates that Terraform Enterprise trusts.

Terraform Enterprise verifies the signature on each SAML response against these certificates. It can trust multiple certificates at the same time and tries each one until a signature validates, so you can run a multi-region IdP, migrate between identity providers, or rotate a certificate without interrupting logins. Refer to Manage IdP certificates for conceptual information.

Request and response documents use the JSON:API resource type saml-idp-certificates.

Certificate attributes

Certificate roles

Terraform Enterprise assigns the legacy_primary and legacy_old roles only through the deprecated idp-cert attribute on Update SAML settings. Every certificate you add through these endpoints is managed.

Certificate lifecycle rules

• You can call every endpoint on this page whether or not SAML is enabled. This lets you add your first certificate before you enable SAML.
• A certificate added while SAML is disabled is inert until you enable SAML.
• Enabling SAML requires at least one certificate with a role of legacy_primary or managed.
• Terraform Enterprise rejects a certificate that it cannot parse, a certificate that has already expired, and a certificate whose fingerprint matches a certificate it already trusts.
• While SAML is enabled, Terraform Enterprise refuses to delete the last certificate with a role of legacy_primary or managed.

List SAML IdP certificates

GET /api/v2/admin/saml-settings/idp-certificates

This endpoint returns every trusted IdP certificate, including the full certificate body. Terraform Enterprise returns the certificates in a deterministic order: the legacy_primary certificate first, then the legacy_old certificate, then managed certificates ordered by when they were last updated.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://tfe.example.com/api/v2/admin/saml-settings/idp-certificates

Sample Response

{
  "data": [
    {
      "id": "idpc-AbC123",
      "type": "saml-idp-certificates",
      "attributes": {
        "display-name": "Migrated Legacy Primary Cert",
        "cert": "-----BEGIN CERTIFICATE-----\nMII...PRIMARY==\n-----END CERTIFICATE-----",
        "fingerprint": "9A:1B:0C:...:F2",
        "issuer": "Example Corp, idp.example.com",
        "expires-at": "2027-01-15T00:00:00Z",
        "created-at": "2026-06-15T10:00:00Z",
        "cert-role": "legacy_primary"
      }
    },
    {
      "id": "idpc-XyZ789",
      "type": "saml-idp-certificates",
      "attributes": {
        "display-name": "EU cluster",
        "cert": "-----BEGIN CERTIFICATE-----\nMII...EU==\n-----END CERTIFICATE-----",
        "fingerprint": "44:7C:1D:...:9D",
        "issuer": "Example Corp, eu.idp.example.com",
        "expires-at": "2027-06-01T00:00:00Z",
        "created-at": "2026-06-16T09:30:00Z",
        "cert-role": "managed"
      }
    }
  ]
}

Show a SAML IdP certificate

GET /api/v2/admin/saml-settings/idp-certificates/:certificate_id

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://tfe.example.com/api/v2/admin/saml-settings/idp-certificates/idpc-XyZ789

Sample Response

{
  "data": {
    "id": "idpc-XyZ789",
    "type": "saml-idp-certificates",
    "attributes": {
      "display-name": "EU cluster",
      "cert": "-----BEGIN CERTIFICATE-----\nMII...EU==\n-----END CERTIFICATE-----",
      "fingerprint": "44:7C:1D:...:9D",
      "issuer": "Example Corp, eu.idp.example.com",
      "expires-at": "2027-06-01T00:00:00Z",
      "created-at": "2026-06-16T09:30:00Z",
      "cert-role": "managed"
    }
  }
}

Add a SAML IdP certificate

POST /api/v2/admin/saml-settings/idp-certificates

This endpoint adds a certificate to the trusted set. Terraform Enterprise derives fingerprint, issuer, and expires-at from the certificate body, and always assigns the managed role. If SAML is enabled, Terraform Enterprise trusts the new certificate immediately.

Request Body

This POST endpoint requires a JSON object with the following properties as a request payload.

Sample Payload

{
  "data": {
    "type": "saml-idp-certificates",
    "attributes": {
      "display-name": "EU cluster",
      "cert": "-----BEGIN CERTIFICATE-----\nMII...EU==\n-----END CERTIFICATE-----"
    }
  }
}

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://tfe.example.com/api/v2/admin/saml-settings/idp-certificates

Sample Response

{
  "data": {
    "id": "idpc-XyZ789",
    "type": "saml-idp-certificates",
    "attributes": {
      "display-name": "EU cluster",
      "cert": "-----BEGIN CERTIFICATE-----\nMII...EU==\n-----END CERTIFICATE-----",
      "fingerprint": "44:7C:1D:...:9D",
      "issuer": "Example Corp, eu.idp.example.com",
      "expires-at": "2027-06-01T00:00:00Z",
      "created-at": "2026-06-16T09:30:00Z",
      "cert-role": "managed"
    }
  }
}

Update a SAML IdP certificate

PATCH /api/v2/admin/saml-settings/idp-certificates/:certificate_id

This endpoint updates a certificate in place. Send display-name to rename the certificate, cert to replace the certificate body, or both. Terraform Enterprise preserves the id, created-at, and cert-role, and re-derives fingerprint, issuer, and expires-at when you replace the body.

You can rename any certificate. You can only replace the body of a managed certificate. To rotate a legacy_primary or legacy_old certificate, use the deprecated idp-cert attribute on Update SAML settings so that Terraform Enterprise preserves the legacy rotation behavior.

Request Body

This PATCH endpoint requires a JSON object with the following properties as a request payload. You can omit either attribute. Omitted attributes keep their previous values.

Sample Payload

The following payload renames the certificate and replaces its body.

{
  "data": {
    "type": "saml-idp-certificates",
    "attributes": {
      "display-name": "EU cluster (primary region)",
      "cert": "-----BEGIN CERTIFICATE-----\nMII...RENEWED==\n-----END CERTIFICATE-----"
    }
  }
}

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request PATCH \
  --data @payload.json \
  https://tfe.example.com/api/v2/admin/saml-settings/idp-certificates/idpc-XyZ789

Sample Response

{
  "data": {
    "id": "idpc-XyZ789",
    "type": "saml-idp-certificates",
    "attributes": {
      "display-name": "EU cluster (primary region)",
      "cert": "-----BEGIN CERTIFICATE-----\nMII...RENEWED==\n-----END CERTIFICATE-----",
      "fingerprint": "E1:9F:2A:...:0C",
      "issuer": "Example Corp, eu.idp.example.com",
      "expires-at": "2028-06-01T00:00:00Z",
      "created-at": "2026-06-16T09:30:00Z",
      "cert-role": "managed"
    }
  }
}

Download a SAML IdP certificate

GET /api/v2/admin/saml-settings/idp-certificates/:certificate_id/download

This endpoint returns the normalized PEM body as a file attachment instead of a JSON:API document. Terraform Enterprise sets Content-Type: application/x-pem-file and names the file idp-cert-<CERTIFICATE ID>.pem.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --request GET \
  --remote-name --remote-header-name \
  https://tfe.example.com/api/v2/admin/saml-settings/idp-certificates/idpc-XyZ789/download

Sample Response

-----BEGIN CERTIFICATE-----
MII...EU==
-----END CERTIFICATE-----

Delete a SAML IdP certificate

DELETE /api/v2/admin/saml-settings/idp-certificates/:certificate_id

This endpoint removes the certificate from the trusted set.

While SAML is enabled, Terraform Enterprise rejects the request when the deletion would leave no certificates with a role of legacy_primary or managed. A legacy_old certificate does not count toward this requirement, so add another certificate or disable SAML first. While SAML is disabled, you can delete any certificate.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  https://tfe.example.com/api/v2/admin/saml-settings/idp-certificates/idpc-XyZ789

Validate a certificate

POST /api/v2/admin/saml-settings/actions/cert-validation

This endpoint inspects a certificate body without storing it. Use it to check a certificate and read its issuer, expiration date, and signature algorithm before you add it.

Validation is not the same as the checks that Add a SAML IdP certificate performs. This endpoint does not enforce the duplicate-fingerprint rule, and it never persists a certificate.

Request Body

This POST endpoint requires a JSON object with the following properties as a request payload.

Response Attributes

When Terraform Enterprise cannot parse the body, it returns "is-valid": false and omits the other attributes. When the body parses but the certificate has expired, Terraform Enterprise returns "is-valid": false along with the issuer, expiration date, and signature algorithm.

Sample Payload

{
  "data": {
    "type": "saml-cert-validations",
    "attributes": {
      "cert": "-----BEGIN CERTIFICATE-----\nMII...EU==\n-----END CERTIFICATE-----"
    }
  }
}

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://tfe.example.com/api/v2/admin/saml-settings/actions/cert-validation

Sample Response

{
  "data": {
    "type": "saml-cert-validations",
    "attributes": {
      "is-valid": true,
      "issuer": "Example Corp, eu.idp.example.com",
      "expires-at": "2027-06-01T00:00:00Z",
      "signature-algorithm": "sha256WithRSAEncryption"
    }
  }
}

Sample Response for an unparseable certificate

{
  "data": {
    "type": "saml-cert-validations",
    "attributes": {
      "is-valid": false
    }
  }
}