# Tokens

Service token management for CI/CD

Source: https://keyenv.dev/docs/api/tokens/

Service token management for CI/CD

## List service tokens

```http
GET /api/v1/tokens
```

Returns all service tokens created by the user

**Operation ID:** `listTokens` &middot; **Authentication:** `Authorization: Bearer <token>`

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | List of tokens | `object` |
| `401` | Authentication required | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `tokens` | `object[]` |  |

### Example

```bash
curl -X GET "https://api.keyenv.dev/api/v1/tokens" \
  -H "Authorization: Bearer $KEYENV_TOKEN"
```

## Create service token

```http
POST /api/v1/tokens
```

Creates a new service token for CI/CD or programmatic access.

**Important:** The token value is only returned once upon creation. Store it securely.

**Operation ID:** `createToken` &middot; **Authentication:** `Authorization: Bearer <token>`

### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | yes |  |
| `team_id` | `string (uuid)` | yes |  |
| `scopes` | `enum (read, write)[]` | yes |  |
| `expires_at` | `string (date-time)` | no | Optional expiration date |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `201` | Token created | `object` |
| `400` | Invalid request | `Error` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |

### Example

```bash
curl -X POST "https://api.keyenv.dev/api/v1/tokens" \
  -H "Authorization: Bearer $KEYENV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","team_id":"00000000-0000-0000-0000-000000000000","scopes":["read"],"expires_at":"string"}'
```

## Delete service token

```http
DELETE /api/v1/tokens/{tokenId}
```

Permanently revokes a service token

**Operation ID:** `deleteToken` &middot; **Authentication:** `Authorization: Bearer <token>`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `tokenId` | `string (uuid)` | yes | Service token UUID |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `204` | Token deleted |  |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |

### Example

```bash
curl -X DELETE "https://api.keyenv.dev/api/v1/tokens/{tokenId}" \
  -H "Authorization: Bearer $KEYENV_TOKEN"
```

## Rotate service token

```http
POST /api/v1/tokens/{tokenId}/rotate
```

Rotates a service token, creating a new one with an optional grace period
during which the old token remains valid. This allows seamless token rotation
in CI/CD systems.

**Operation ID:** `rotateToken` &middot; **Authentication:** `Authorization: Bearer <token>`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `tokenId` | `string (uuid)` | yes | Service token UUID |

### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `grace_period_minutes` | `integer` | no | How long the old token remains valid |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | Token rotated successfully | `RotateTokenResponse` |
| `401` | Authentication required | `Error` |
| `403` | Insufficient permissions | `Error` |
| `404` | Resource not found | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `new_token` | `object` |  |
| `old_token_expires_at` | `string (date-time)` |  |

### Example

```bash
curl -X POST "https://api.keyenv.dev/api/v1/tokens/{tokenId}/rotate" \
  -H "Authorization: Bearer $KEYENV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"grace_period_minutes":5}'
```