Team tokens API reference

Team API tokens grant access to a team's workspaces. Each team can have an API token that is not associated with a specific user. You can create and delete team tokens and list an organization's team tokens.

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 this token when you create it and can not 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

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 `"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 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/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"
        }
      }
    }
  }
}