User tokens API reference
List User Tokens
GET /users/:user_id/authentication-tokens
| Parameter | Description |
|---|---|
:user_id | The ID of the User. |
Use theAccount API to find your own user ID.
The objects returned by this endpoint only contain metadata, and do not include the secret text of any authentication tokens. A token is only shown upon creation, and cannot be recovered later.
Note: You must access this endpoint with auser token, and it will only return useful data for that token's user account.
| Status | Response | Reason |
|---|---|---|
| 200 | JSON API document (type: "authentication-tokens") | The request was successful |
| 200 | EmptyJSON API document (no type) | User has no authentication tokens, or request was made by someone other than the user |
| 404 | JSON API error object | User not found |
Query Parameters
This endpoint supports paginationwith 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.
| Parameter | Description |
|---|---|
page[number] | Optional. If omitted, the endpoint will return the first page. |
page[size] | Optional. If omitted, the endpoint will return 20 user tokens per page. |
Sample Request
curl \ --header "Authorization: Bearer $TOKEN" \ --header "Content-Type: application/vnd.api+json" \ --request GET \ https://app.terraform.io/api/v2/users/user-MA4GL63FmYRpSFxa/authentication-tokensSample Response
{ "data": [ { "id": "at-QmATJea6aWj1xR2t", "type": "authentication-tokens", "attributes": { "created-at": "2018-11-06T22:56:10.203Z", "last-used-at": null, "description": null, "token": null, "expired-at": null }, "relationships": { "created-by": { "data": null } } }, { "id": "at-6yEmxNAhaoQLH1Da", "type": "authentication-tokens", "attributes": { "created-at": "2018-11-25T22:31:30.624Z", "last-used-at": "2018-11-26T20:27:54.931Z", "description": "api", "token": null, "expired-at": "2023-04-06T12:00:00.000Z" }, "relationships": { "created-by": { "data": { "id": "user-MA4GL63FmYRpSFxa", "type": "users" } } } } ]}Show a User Token
GET /authentication-tokens/:id
| Parameter | Description |
|---|---|
:id | The ID of the User Token. |
The objects returned by this endpoint only contain metadata, and do not include the secret text of any authentication tokens. A token is only shown upon creation, and cannot be recovered later.
Note: You must access this endpoint with auser token, and it will only return useful data for that token's user account.
| Status | Response | Reason |
|---|---|---|
| 200 | JSON API document (type: "authentication-tokens") | The request was successful |
| 404 | JSON API error object | User Token not found, or unauthorized to view the User 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-6yEmxNAhaoQLH1DaSample Response
{ "data": { "id": "at-6yEmxNAhaoQLH1Da", "type": "authentication-tokens", "attributes": { "created-at": "2018-11-25T22:31:30.624Z", "last-used-at": "2018-11-26T20:34:59.487Z", "description": "api", "token": null, "expired-at": "2023-04-06T12:00:00.000Z" }, "relationships": { "created-by": { "data": { "id": "user-MA4GL63FmYRpSFxa", "type": "users" } } } }}Create a User Token
POST /users/:user_id/authentication-tokens
| Parameter | Description |
|---|---|
:user_id | The ID of the User. |
Use theAccount API to find your own user ID.
This endpoint returns the secret text of the created authentication token. A token is only shown upon creation, and cannot be recovered later.
Note: You must access this endpoint with auser token, and it will only create new tokens for that token's user account.
| Status | Response | Reason |
|---|---|---|
| 201 | JSON API document (type: "authentication-tokens") | The request was successful |
| 404 | JSON API error object | User not found or user unauthorized to perform action |
| 422 | JSON API error object | Malformed request body (missing attributes, wrong types, etc.) |
| 500 | JSON API error object | Failure during User Token creation |
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 | The description for the User Token. | |
data.attributes.expired-at | string | null | The UTC date and time that the User Token will expire, in ISO 8601 format. If omitted or set tonull the token will never expire. |
Sample Payload
{ "data": { "type": "authentication-tokens", "attributes": { "description":"api", "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/users/user-MA4GL63FmYRpSFxa/authentication-tokensSample Response
{ "data": { "id": "at-MKD1X3i4HS3AuD41", "type": "authentication-tokens", "attributes": { "created-at": "2018-11-26T20:48:35.054Z", "last-used-at": null, "description": "api", "token": "6tL24nM38M7XWQ.atlasv1.KmWckRfzeNmUVFNvpvwUEChKaLGznCSD6fPf3VPzqMMVzmSxFU0p2Ibzpo2h5eTGwPU", "expired-at": "2023-04-06T12:00:00.000Z" }, "relationships": { "created-by": { "data": { "id": "user-MA4GL63FmYRpSFxa", "type": "users" } } } }}Destroy a User Token
DELETE /authentication-tokens/:id
| Parameter | Description |
|---|---|
:id | The ID of the User Token to destroy. |
Note: You must access this endpoint with auser token, and it will only delete tokens for that token's user account.
| Status | Response | Reason |
|---|---|---|
| 204 | Empty response | The User Token was successfully destroyed |
| 404 | JSON API error object | User Token not found, or user unauthorized to perform action |
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