Team tokens API reference

Team API tokens grant access to a team's workspaces. Teams are not limited to a single token, and can have multiple tokens at a time. Team tokens are not associated with a specific user.

Teams relying on the legacy team token API (/teams/:team_id/authentication-token), can only create a single, valid token at a time. Generating a new legacy token when one already exists for the team revokes the existing legacy token, replacing it with a new team token.

You can create and delete team tokens and list an organization's team tokens.

Generate a new team token

Generates a new team token.

Method	Path
POST	/teams/:team_id/authentication-tokens

This endpoint returns the secret text of the new authentication token. You can only access the secret text when you create it and cannot recover it later.

Parameters

:team_id (string: <required>) - specifies the team ID for generating the team token

Request body

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

Key path	Type	Default	Description
`data.type`	string		Must be `"authentication-tokens"`.
`data.attributes.description`	string		The description of the team token. Each description must be unique within the context of the team.
`data.attributes.expired-at`	string	`null`	The UTC date and time that the Team Token will expire, in ISO 8601 format. If omitted or set to `null` the token will never expire.

Sample payload

{
  "data": {
    "type": "authentication-tokens",
    "attributes": {
      "description": "Team API token for team ABC",
      "expired-at": "2023-04-06T12:00:00.000Z"
    }
  }
}

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/teams/team-BUHBEM97xboT8TVz/authentication-tokens

Sample response

{
  "data": {
    "id": "4111797",
    "type": "authentication-tokens",
    "attributes": {
      "created-at": "2017-11-29T19:18:09.976Z",
      "last-used-at": null,
      "description": "Team API token for team ABC",
      "token": "QnbSxjjhVMHJgw.atlasv1.gxZnWIjI5j752DGqdwEUVLOFf0mtyaQ00H9bA1j90qWb254lEkQyOdfqqcq9zZL7Sm0",
      "expired-at": "2023-04-06T12:00:00.000Z"
    },
    "relationships": {
      "team": {
        "data": {
          "id": "team-Y7RyjccPVBKVEdp7",
          "type": "teams"
        }
      },
      "created-by": {
        "data": {
          "id": "user-62goNpx1ThQf689e",
          "type": "users"
        }
      }
    }
  }
}

Delete a team token

Method	Path
DELETE	/authentication-tokens/:token_id

Parameters

:token_id (string: <required>) - specifies the token_id from which to delete the token

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  https://app.terraform.io/api/v2/authentication-tokens/at-6yEmxNAhaoQLH1Da

List team tokens

Lists the team tokens for the team.

GET /organizations/:organization_id/team-tokens

Parameter	Description
`:organization_id`	The ID of the organization whose team tokens you want to list.

This endpoint returns object metadata and does not include secret authentication details of tokens. You can only view a token when you create it and cannot recover it later.

Status	Response	Reason
200	JSON API document (`type: "team-tokens"`)	The request was successful.
200	Empty JSON API document	The specified team has no team tokens.
404	JSON API error object	Team not found.

Query parameters

This endpoint supports pagination with standard URL query parameters and searching with the q parameter. Remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

Parameter	Description
`page[number]`	Optional. If omitted, the endpoint returns the first page.
`page[size]`	Optional. If omitted, the endpoint returns 20 tokens per page.
`q`	Optional. A search query string. You can search for a team authentication token using the team name.
`sort`	Optional. Allows sorting the team tokens by `"created-by"`, `"expired-at"`, and `"last-used-at"`. Prepending a hyphen to the sort parameter reverses the order. If omitted, the default sort order ascending.

Sample response

{
  "data": [
    {
      "id": "at-TLhN8cc6ro6qYDvp",
      "type": "authentication-tokens",
      "attributes": {
      "created-at": "2017-11-29T19:18:09.976Z",
      "last-used-at": null,
      "description": "Team API token for team ABC",
      "token": "QnbSxjjhVMHJgw.atlasv1.gxZnWIjI5j752DGqdwEUVLOFf0mtyaQ00H9bA1j90qWb254lEkQyOdfqqcq9zZL7Sm0",
      "expired-at": "2023-04-06T12:00:00.000Z"
      },
      "relationships": {
        "team": {
          "data": {
            "id": "team-Y7RyjccPVBKVEdp7",
            "type": "teams"
          }
        },
        "created-by": {
          "data": {
            "id": "user-ccU6h629sszLJBpY",
            "type": "users"
          }
        }
      }
    },
    {
      "id": "at-qfc2wqqJ1T5sCamM",
      "type": "authentication-tokens",
      "attributes": {
        "created-at": "2024-06-19T18:44:44.051Z",
        "last-used-at": null,
        "description": "Team API token for team XYZ",
        "token": null,
        "expired-at": "2024-07-19T18:44:43.818Z"
      },
      "relationships": {
        "team": {
          "data": {
            "id": "team-58pFiBffTLMxLphR",
            "type": "teams"
          }
        },
        "created-by": {
          "data": {
            "id": "user-ccU6h629hhzLJBpY",
            "type": "users"
          }
        }
      }
    },
  ]
}

Show a team token

Use this endpoint to display a particular team token.

GET /authentication-tokens/:token_id

Parameter	Description
`:token_id`	The ID of the Team Token.

The object returned by this endpoint only contains metadata, and does not include the secret text of the authentication token. A token's secret test is only shown upon creation, and cannot be recovered later.

Status	Response	Reason
200	JSON API document (`type: "authentication-tokens"`)	The request was successful
404	JSON API error object	Team Token not found, or unauthorized to view the Team Token

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/authentication-tokens/at-6yEmxNAhaoQLH1Da

Sample response

{
  "data": {
    "id": "at-6yEmxNAhaoQLH1Da",
    "type": "authentication-tokens",
    "attributes": {
      "created-at": "2017-11-29T19:18:09.976Z",
      "last-used-at": null,
      "description": "Team API token for team ABC",
      "token": "QnbSxjjhVMHJgw.atlasv1.gxZnWIjI5j752DGqdwEUVLOFf0mtyaQ00H9bA1j90qWb254lEkQyOdfqqcq9zZL7Sm0",
      "expired-at": "2023-04-06T12:00:00.000Z"
    },
    "relationships": {
      "team": {
        "data": {
          "id": "team-LnREdjodkvZFGdXL",
          "type": "teams"
        }
      },
      "created-by": {
        "data": {
          "id": "user-MA4GL63FmYRpSFxa",
          "type": "users"
        }
      }
    }
  }
}

Legacy team tokens API reference

Legacy team API tokens grant access to a team's workspaces. Each team can have a single legacy API token that is not associated with a specific user. You can create and delete team tokens and list an organization's team tokens. The team tokens API includes the same functionality as legacy team tokens, and allows you to provision multiple tokens with descriptions per team.

Generate a new team token

Generates a new team token and overrides existing token if one exists.

Method	Path
POST	/teams/:team_id/authentication-token

This endpoint returns the secret text of the new authentication token. You can only access the secret when you create it and cannot recover it later.

Parameters

:team_id (string: <required>) - specifies the team ID for generating the team token

Request body

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

Key path	Type	Default	Description
`data.type`	string		Must be `"authentication-token"`.
`data.attributes.expired-at`	string	`null`	The UTC date and time that the Team Token will expire, in ISO 8601 format. If omitted or set to `null` the token will never expire.

Sample payload

{
  "data": {
    "type": "authentication-token",
    "attributes": {
      "expired-at": "2023-04-06T12:00:00.000Z"
    }
  }
}

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/teams/team-BUHBEM97xboT8TVz/authentication-token

Sample response

{
  "data": {
    "id": "4111797",
    "type": "authentication-tokens",
    "attributes": {
      "created-at": "2017-11-29T19:18:09.976Z",
      "last-used-at": null,
      "description": null,
      "token": "QnbSxjjhVMHJgw.atlasv1.gxZnWIjI5j752DGqdwEUVLOFf0mtyaQ00H9bA1j90qWb254lEkQyOdfqqcq9zZL7Sm0",
      "expired-at": "2023-04-06T12:00:00.000Z"
    },
    "relationships": {
      "team": {
        "data": {
          "id": "team-Y7RyjccPVBKVEdp7",
          "type": "teams"
        }
      },
      "created-by": {
        "data": {
          "id": "user-62goNpx1ThQf689e",
          "type": "users"
        }
      }
    }
  }
}

Delete the team token

Method	Path
DELETE	/teams/:team_id/authentication-token

Parameters

:team_id (string: <required>) - specifies the team_id from which to delete the token

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  https://app.terraform.io/api/v2/teams/team-BUHBEM97xboT8TVz/authentication-token

List team tokens

Lists the team tokens in an organization.

GET organizations/:organization_name/team-tokens

Parameter	Description
`:organization_name`	The name of the organization whose team tokens you want to list.

This endpoint returns object metadata and does not include secret authentication details of tokens. You can only view a token when you create it and cannot recover it later.

By default, this endpoint returns tokens by ascending expiration date.

Status	Response	Reason
200	JSON API document (`type: "team-tokens"`)	The request was successful.
200	Empty JSON API document	The specified organization has no team tokens.
404	JSON API error object	Organization not found.

Query parameters

Parameter	Description
`page[number]`	Optional. If omitted, the endpoint returns the first page.
`page[size]`	Optional. If omitted, the endpoint returns 20 tokens per page.
`q`	Optional. A search query string. You can search for a team authentication token using the team name.
`sort`	Optional. Allows sorting the team tokens by `"team-name"`, `"created-by"`, `"expired-at"`, and `"last-used-at"`. Prepending a hyphen to the sort parameter reverses the order. For example, `"-team-name"` sorts by name in reverse alphabetical order. If omitted, the default sort order ascending.

Sample response

{
  "data": [
    {
      "id": "at-TLhN8cc6ro6qYDvp",
      "type": "authentication-tokens",
      "attributes": {
        "created-at": "2024-06-19T18:28:25.267Z",
        "last-used-at": null,
        "description": null,
        "token": null,
        "expired-at": "2024-07-19T18:28:25.030Z"
      },
      "relationships": {
        "team": {
          "data": {
            "id": "team-Y7RyjccPVBKVEdp7",
            "type": "teams"
          }
        },
        "created-by": {
          "data": {
            "id": "user-ccU6h629sszLJBpY",
            "type": "users"
          }
        }
      }
    },
    {
      "id": "at-qfc2wqqJ1T5sCamM",
      "type": "authentication-tokens",
      "attributes": {
        "created-at": "2024-06-19T18:44:44.051Z",
        "last-used-at": null,
        "description": null,
        "token": null,
        "expired-at": "2024-07-19T18:44:43.818Z"
      },
      "relationships": {
        "team": {
          "data": {
            "id": "team-58pFiBffTLMxLphR",
            "type": "teams"
          }
        },
        "created-by": {
          "data": {
            "id": "user-ccU6h629hhzLJBpY",
            "type": "users"
          }
        }
      }
    },
  ]
}

Show a team token

Use this endpoint to display a team token for a particular team.

GET /teams/:team_id/authentication-token

Parameter	Description
`:team_id`	The ID of the Team.

You can also fetch a team token directly by using the token's ID with the authentication-tokens/ endpoint.

GET /authentication-tokens/:token_id

Parameter	Description
`:token_id`	The ID of the Team Token.

The object returned by this endpoint only contains metadata, and does not include the secret text of the authentication token. A token's secret text is only shown upon creation, and cannot be recovered later.

Status	Response	Reason
200	JSON API document (`type: "authentication-tokens"`)	The request was successful
404	JSON API error object	Team Token not found, or unauthorized to view the Team Token

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/teams/team-6yEmxNAhaoQLH1Da/authentication-token

Sample response

{
  "data": {
    "id": "at-6yEmxNAhaoQLH1Da",
    "type": "authentication-tokens",
    "attributes": {
      "created-at": "2023-11-25T22:31:30.624Z",
      "last-used-at": "2023-11-26T20:34:59.487Z",
      "description": null,
      "token": null,
      "expired-at": "2024-04-06T12:00:00.000Z"
    },
    "relationships": {
      "team": {
        "data": {
          "id": "team-LnREdjodkvZFGdXL",
          "type": "teams"
        }
      },
      "created-by": {
        "data": {
          "id": "user-MA4GL63FmYRpSFxa",
          "type": "users"
        }
      }
    }
  }
}