SCIM tokens API reference

This topic provides reference information for the SCIM /authentication-token endpoints. Your identity provider uses a SCIM token to authenticate requests to the SCIM provisioning endpoints.

SCIM tokens belong to the organization's SCIM configuration. If you delete the SCIM configuration, all associated SCIM tokens are also deleted.

Only members of the owners team or an owners team API token can access these endpoints.

List SCIM tokens

GET /scim-configurations/:scim_configuration_id/authentication-tokens

This endpoint lists the SCIM tokens for an organization's SCIM configuration.

Path parameters

Parameter	Description
`:scim_configuration_id`	The external ID of the organization's SCIM configuration.

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.

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.

Response codes

Status	Response	Reason
200	JSON API document (`type: "authentication-tokens"`)	Successfully returned the SCIM tokens
404	JSON API error object	SCIM configuration not found or user unauthorized to perform action

Sample request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --request GET \
  https://app.terraform.io/api/v2/scim-configurations/scimconf-cUhcmDfss7fapMqXWtruZZATRLMTU9/authentication-tokens

Sample response

{
  "data": [
    {
      "id": "at-6yEmxNAhaoQLH1Da",
      "type": "authentication-tokens",
      "attributes": {
        "created-at": "2026-01-09T19:52:36.114Z",
        "last-used-at": "2026-01-14T08:11:02.371Z",
        "description": "Token for IdP",
        "token": null,
        "expired-at": "2027-01-09T19:52:36.114Z",
        "is-ttl-rejected": false
      },
      "relationships": {
        "created-by": {
          "data": {
            "id": "user-62goNpx1ThQf689e",
            "type": "users"
          }
        }
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/scim-configurations/scimconf-cUhcmDfss7fapMqXWtruZZATRLMTU9/authentication-tokens?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/v2/scim-configurations/scimconf-cUhcmDfss7fapMqXWtruZZATRLMTU9/authentication-tokens?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/v2/scim-configurations/scimconf-cUhcmDfss7fapMqXWtruZZATRLMTU9/authentication-tokens?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "prev-page": null,
      "next-page": null,
      "total-pages": 1,
      "total-count": 1
    }
  }
}

Create a SCIM token

POST /scim-configurations/:scim_configuration_id/authentication-tokens

This endpoint creates a SCIM token for an organization's SCIM configuration.

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

Path parameters

Parameter	Description
`:scim_configuration_id`	The external ID of the organization's SCIM configuration.

Response codes

Status	Response	Reason
201	JSON API document (`type: "authentication-tokens"`)	Successfully created the SCIM token
400	JSON API error object	The expiration is outside the supported range or is not a valid date
404	JSON API error object	SCIM configuration not found, or user unauthorized to perform action

Request body

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

Properties without a default value are required.

Key path	Type	Default	Description
`data.type`	string		Must be `"authentication-tokens"`.
`data.attributes.description`	string	`null`	The description of the SCIM token.
`data.attributes.expired-at`	string	One year	The UTC date and time that the token expires in ISO 8601 format. The expiration must be at least 30 days and at most one year from the time of creation.

Sample payload

{
  "data": {
    "type": "authentication-tokens",
    "attributes": {
      "description": "Token for IdP",
      "expired-at": "2027-01-09T19:52:36.114Z"
    }
  }
}

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/scim-configurations/scimconf-cUhcmDfss7fapMqXWtruZZATRLMTU9/authentication-tokens

Sample response

{
  "data": {
    "id": "at-6yEmxNAhaoQLH1Da",
    "type": "authentication-tokens",
    "attributes": {
      "created-at": "2026-01-09T19:52:36.114Z",
      "last-used-at": null,
      "description": "Token for IdP",
      "token": "QnbSxjjhVMHJgw.atlasv1.gxZnWIjI5j752DGqdwEUVLOFf0mtyaQ00H9bA1j90qWb254lEkQyOdfqqcq9zZL7Sm0",
      "expired-at": "2027-01-09T19:52:36.114Z",
      "is-ttl-rejected": false
    },
    "relationships": {
      "created-by": {
        "data": {
          "id": "user-62goNpx1ThQf689e",
          "type": "users"
        }
      }
    }
  }
}

Show a SCIM token

GET /authentication-tokens/:token_id

This endpoint returns a single SCIM token. The object returned by this endpoint only contains metadata and does not include the secret text of the token.

Path parameters

Parameter	Description
`:token_id`	The ID of the SCIM token.

Response codes

Status	Response	Reason
200	JSON API document (`type: "authentication-tokens"`)	Successfully returned the SCIM token
404	JSON API error object	Token not found, or user unauthorized to perform action

Sample request

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

Sample response

{
  "data": {
    "id": "at-6yEmxNAhaoQLH1Da",
    "type": "authentication-tokens",
    "attributes": {
      "created-at": "2026-01-09T19:52:36.114Z",
      "last-used-at": "2026-01-14T08:11:02.371Z",
      "description": "Token for IdP",
      "token": null,
      "expired-at": "2027-01-09T19:52:36.114Z",
      "is-ttl-rejected": false
    },
    "relationships": {
      "created-by": {
        "data": {
          "id": "user-62goNpx1ThQf689e",
          "type": "users"
        }
      }
    }
  }
}

Delete a SCIM token

DELETE /authentication-tokens/:token_id

This endpoint deletes a SCIM token.

Path parameters

Parameter	Description
`:token_id`	The ID of the SCIM token to delete.

Response codes

Status	Response	Reason
204	Empty response	Successfully deleted the SCIM token
404	JSON API error object	Token not found, or user unauthorized to perform action

Sample request

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

Sample response

A successful request returns a 204 No Content response with no body.