SSH keys API reference

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:

• You can assign them to VCS provider integrations, which are available in the API as oauth-tokens. Refer to OAuth Tokens for additional information. Azure DevOps Server and Bitbucket Data Center require an SSH key. Other providers only require an SSH key when your repositories include submodules that are only accessible using an SSH connection 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 HCP Terraform's private module registry.

Listing and viewing SSH keys requires either permission to manage VCS settings for the organization, or admin access to at least one workspace. (More about permissions.)

List SSH Keys

GET /organizations/:organization_name/ssh-keys

Query Parameters

This endpoint supports pagination with standard URL query parameters. Remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs. If neither pagination query parameters are provided, the endpoint will not be paginated and will return all results.

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" \
  --header "Content-Type: application/vnd.api+json" \
  --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 of an existing SSH key.

Editing SSH keys requires permission to manage VCS settings. (More about permissions.)

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" \
  --header "Content-Type: application/vnd.api+json" \
  --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

Deleting SSH keys requires permission to manage VCS settings. (More about permissions.)

Sample Request

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