# API Tokens

API Tokens allow you to access TeraSwitch services programmatically. Each token is scoped to a specific project and can have different permission levels.

### Accessing API Tokens

1. Go to **Settings**
2. Select **Project** scope
3. Click **API Tokens** tab

### Token List

The tokens table displays:

| Column               | Description                 |
| -------------------- | --------------------------- |
| Token Id             | Unique identifier (partial) |
| Display Name         | Human-readable name         |
| Role                 | Permission level            |
| Status               | Active/Inactive             |
| Created (Local Time) | When token was created      |
| Actions              | Management options          |

#### Token Roles

| Role           | Permissions                           |
| -------------- | ------------------------------------- |
| **Owner**      | Full access to all project resources  |
| **Accounting** | Read access to billing and usage data |

### Generating a New Token

1. Click **Generate New Token**
2. Enter a **Display Name**:
   * Use descriptive names
   * Include purpose/application
   * Example: "production-api-client"
3. Select **Role**:
   * Owner for full access
   * Accounting for read-only billing
4. Click **Generate**

#### Token Secret

After generation, you'll see the token secret **once**:

{% hint style="danger" %}
**Copy your token immediately!** The secret is only shown once and cannot be retrieved later.
{% endhint %}

Store the token securely:

* Use a secrets manager
* Never commit to source control
* Rotate regularly

### Managing Tokens

#### Viewing Tokens

The list shows all tokens for the current project:

* Token ID (partial for security)
* Display name
* Role and status
* Creation date

#### Revoking Tokens

To revoke (delete) a token:

1. Find the token
2. Click **Actions** > **Revoke**
3. Confirm revocation

{% hint style="warning" %}
Revoked tokens immediately stop working. Any systems using the token will lose access.
{% endhint %}

\## Using API Tokens

#### Authentication

Include the token in API requests:

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.teraswitch.com/v1/instances
```

#### Developer Resources

API documentation is available at [developer.tsw.io](https://developer.tsw.io).

### Best Practices

#### Token Management

* **Descriptive Names**: Include purpose and owner
* **Minimal Permissions**: Use Accounting role when possible
* **Regular Rotation**: Replace tokens periodically
* **Quick Revocation**: Remove unused tokens immediately

#### Security

* **Never Share**: Each application should have its own token
* **Secure Storage**: Use environment variables or secrets managers
* **No Hard-coding**: Never embed tokens in source code
* **Monitor Usage**: Watch for unusual API activity

#### Per-Application Tokens

Create separate tokens for:

* Different applications
* Different environments (dev/staging/prod)
* Different team members
* CI/CD pipelines

This allows:

* Granular revocation
* Better audit trails
* Isolated access

#### Rotation Schedule

Implement token rotation:

1. Generate new token
2. Update applications
3. Verify new token works
4. Revoke old token

Consider rotating:

* Quarterly for standard tokens
* Immediately if compromised
* When team members leave

### Troubleshooting

#### Token Not Working

Check:

1. Token is Active status
2. Correct project scope
3. Token has required permissions
4. Token hasn't been revoked

#### Lost Token Secret

If you lose a token secret:

1. Generate a new token
2. Update your applications
3. Revoke the old token

Token secrets cannot be recovered.

#### Rate Limiting

API requests may be rate limited:

* Implement exponential backoff
* Cache responses when appropriate
* Contact support for higher limits

### Integration Examples

#### Python

```python
import requests

API_TOKEN = "your_token_here"
BASE_URL = "https://api.teraswitch.com/v1"

headers = {"Authorization": f"Bearer {API_TOKEN}"}

response = requests.get(f"{BASE_URL}/instances", headers=headers)
instances = response.json()
```

#### Terraform

```hcl
provider "teraswitch" {
  token = var.teraswitch_token
}
```

#### CI/CD

Store token as a secret:

* GitHub Actions: Repository secrets
* GitLab CI: CI/CD variables
* Jenkins: Credentials plugin


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.teraswitch.com/account/api-tokens.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.