» SSH Keys

The ssh-key object represents an SSH key which includes a name and the SSH private key. An organization can have multiple SSH keys available.

SSH keys can be used in two places:

• They can be assigned to VCS provider integrations (available in the API as oauth-tokens). Bitbucket Server requires an SSH key; other providers only need an SSH key if your repositories include submodules that are only accessible via SSH (instead of your VCS provider's API).
• They can be assigned to workspaces and used when Terraform needs to clone modules from a Git server. This is only necessary when your configurations directly reference modules from a Git server; you do not need to do this if you use Terraform Enterprise's private module registry.

» List SSH Keys

GET /organizations/:organization_name/ssh-keys

» Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  https://app.terraform.io/api/v2/organizations/my-organization/ssh-keys

» Sample Response

{
  "data": [
    {
      "attributes": {
        "name": "SSH Key"
      },
      "id": "sshkey-GxrePWre1Ezug7aM",
      "links": {
        "self": "/api/v2/ssh-keys/sshkey-GxrePWre1Ezug7aM"
      },
      "type": "ssh-keys"
    }
  ]
}

» Get an SSH Key

GET /ssh-keys/:ssh_key_id

This endpoint is for looking up the name associated with an SSH key ID. It does not retrieve the key text.

» Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  https://app.terraform.io/api/v2/ssh-keys/sshkey-GxrePWre1Ezug7aM

» Sample Response

{
  "data": {
    "attributes": {
      "name": "SSH Key"
    },
    "id": "sshkey-GxrePWre1Ezug7aM",
    "links": {
      "self": "/api/v2/ssh-keys/sshkey-GxrePWre1Ezug7aM"
    },
    "type": "ssh-keys"
  }
}

» Create an SSH Key

POST /organizations/:organization_name/ssh-keys

» Request Body

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

Properties without a default value are required.

» Sample Payload

{
  "data": {
    "type": "ssh-keys",
    "attributes": {
      "name": "SSH Key",
      "value": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAm6+JVgl..."
    }
  }
}

» Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/organizations/my-organization/ssh-keys

» Sample Response

{
  "data": {
    "attributes": {
      "name": "SSH Key"
    },
    "id": "sshkey-GxrePWre1Ezug7aM",
    "links": {
      "self": "/api/v2/ssh-keys/sshkey-GxrePWre1Ezug7aM"
    },
    "type": "ssh-keys"
  }
}

» Update an SSH Key

PATCH /ssh-keys/:ssh_key_id

This endpoint replaces the name and/or key text of an existing SSH key. Existing workspaces that use the key will be updated with the new values.

Only members of the owners team (or the owners team service account) can edit SSH keys.

» Request Body

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

Properties without a default value are required.

» Sample Payload

{
  "data": {
    "attributes": {
      "name": "SSH Key for GitHub"
    }
  }
}

» Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --request PATCH \
  --data @payload.json \
  https://app.terraform.io/api/v2/ssh-keys/sshkey-GxrePWre1Ezug7aM

» Sample Response

{
  "data": {
    "attributes": {
      "name": "SSH Key for GitHub"
    },
    "id": "sshkey-GxrePWre1Ezug7aM",
    "links": {
      "self": "/api/v2/ssh-keys/sshkey-GxrePWre1Ezug7aM"
    },
    "type": "ssh-keys"
  }
}

» Delete an SSH Key

DELETE /ssh-keys/:ssh_key_id

Only members of the owners team (or the owners team service account) can delete SSH keys.

» Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --request DELETE \
  https://app.terraform.io/api/v2/ssh-keys/sshkey-GxrePWre1Ezug7aM