Access Tokens API

API access tokens allow you to programmatically interact with the Terrateam API. These endpoints enable you to create, list, refresh, and delete tokens.

Create Access Token

Create a new API access token.

Endpoint: POST /api/v1/{vcs}/access-token

Path Parameters:

Name	Type	Required	Description
`vcs`	string	Yes	VCS provider: `github` or `gitlab`

Request Body:

Content-Type: application/json

Schema: access-token-create

{
  "name": "string",
  "capabilities": [
    "kv_store_read",
    "kv_store_write",
    {
      "name": "installation_id",
      "id": "12345"
    }
  ]
}

See Available Capabilities below for all options.

Responses:

200: Success - Returns the created access token
400: Bad Request
403: Forbidden

Response Schema (200):

Schema: access-token

{
  "refresh_token": "string"
}

Example Request:

curl -X POST \
  https://app.terrateam.io/api/v1/github/access-token \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Token",
    "capabilities": ["kv_store_read", "kv_store_write"]
  }'

List Access Tokens

Retrieve a paginated list of access tokens.

Endpoint: GET /api/v1/{vcs}/access-token

Path Parameters:

Name	Type	Required	Description
`vcs`	string	Yes	VCS provider: `github` or `gitlab`

Query Parameters:

Name	Type	Required	Description
`limit`	integer	No	Maximum number of results
`page`	array[string]	No	Pagination token

Responses:

200: Success - Returns access token page
403: Forbidden

Response Schema (200):

Schema: access-token-page

{
  "results": [
    {
      "id": "string",
      "name": "string",
      "capabilities": [
        "kv_store_read",
        "kv_store_write",
        {
          "name": "installation_id",
          "id": "12345"
        }
      ]
    }
  ]
}

Example Request:

curl -X GET \
  "https://app.terrateam.io/api/v1/github/access-token?limit=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Delete Access Token

Delete an access token by ID.

Endpoint: DELETE /api/v1/{vcs}/access-token

Path Parameters:

Name	Type	Required	Description
`vcs`	string	Yes	VCS provider: `github` or `gitlab`

Query Parameters:

Name	Type	Required	Description
`id`	string	Yes	The access token ID to delete

Responses:

200: Success
403: Forbidden
404: Not Found

Example Request:

curl -X DELETE \
  "https://app.terrateam.io/api/v1/github/access-token?id=TOKEN_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Refresh Access Token

Exchange your API key for a short-lived access token with the capabilities you selected when creating the API key.

Endpoint: POST /api/v1/access-token/refresh

Authentication: Use your API key (created in the Terrateam UI) as the Bearer token.

Responses:

200: Success - Returns new access token
403: Forbidden

Response Schema (200):

{
  "token": "string"
}

Example Request:

curl -X POST \
  https://app.terrateam.io/api/v1/access-token/refresh \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Token Management

Understanding the Token Types

API Key (Long-lived)

Created in the Terrateam UI at Settings > API Access
Has one capability: refreshing to get access tokens
Stores the actual capabilities you select in the UI
Should be stored securely and rotated periodically
Managed via the /api/v1/{vcs}/access-token endpoints

Access Token (Short-lived)

Obtained by calling /api/v1/access-token/refresh with your API key
Inherits the capabilities from the API key
Used for actual API requests
Expires after 60 seconds (refresh to get a new one)

Available Capabilities

When creating an API access token, you can specify one or more capabilities that define what the token can do. Capabilities can be either simple strings or objects with additional properties.

String Capabilities

These capabilities are specified as simple strings:

Capability	Description
`access_token_refresh`	Allows refreshing access tokens to get new short-lived tokens
`access_token_create`	Allows creating new API access tokens
`kv_store_read`	Grants read access to the key-value store
`kv_store_write`	Grants write access to the key-value store
`kv_store_system_read`	Grants read access to the system key-value store
`kv_store_system_write`	Grants write access to the system key-value store

Example:

{
  "name": "My Token",
  "capabilities": ["kv_store_read", "kv_store_write"]
}

Object Capabilities

These capabilities require additional properties:

Installation ID

Scope the token to a specific installation.

{
  "name": "installation_id",
  "id": "12345"
}

Properties:

name: Must be "installation_id"
id: The installation ID string

VCS Provider

Scope the token to a specific VCS provider.

{
  "name": "vcs",
  "vcs": "github"
}

Properties:

name: Must be "vcs"
vcs: The VCS provider ("github" or "gitlab")

Combined Example

You can mix string and object capabilities:

{
  "name": "Production Token",
  "capabilities": [
    "kv_store_read",
    "kv_store_write",
    {
      "name": "installation_id",
      "id": "67890"
    },
    {
      "name": "vcs",
      "vcs": "github"
    }
  ]
}

Authentication

The endpoints on this page manage API keys. To use these endpoints, you need an access token:

For /api/v1/access-token/refresh: Use your API key (the one you created in the UI)
For all other endpoints (/api/v1/{vcs}/access-token): Use an access token obtained from the refresh endpoint

Authorization: Bearer YOUR_TOKEN

See the Authentication guide for detailed instructions.