# Tokens

> Create, manage, and revoke workspace tokens that authenticate access to your gateway URL.

Workspace tokens authenticate requests to the MCP gateway. Each token is a `mwt_` prefixed string that grants access to all tools in the workspace. Tokens are SHA-256 hashed before storage -- Aerostack never stores the raw token value.

---

## How Tokens Work

1. You **create** a token for a workspace (via the dashboard or CLI)
2. The raw token (`mwt_...`) is returned **exactly once** in the response
3. When a request hits the gateway, the token is SHA-256 hashed and verified against the stored hash
4. If valid, not expired, and not revoked, the request is authorized

  **Save the token immediately.** The raw token value is shown only once at creation time. If you lose it, you must revoke it and create a new one.

---

## Create a Token

### Dashboard

1. **Open Your Workspace**

   Navigate to **Workspaces** in the Admin dashboard and select a workspace.

1. **Go to Tokens**

   Click the **Tokens** tab. You will see a list of existing tokens for this workspace.

1. **Create Token**

   Click **New Token**. Enter a name (for example, "Alice Cursor", "CI Bot", "Production Bot") and optionally set an expiration time.

1. **Copy the Token**

   The raw token is displayed once. Copy it immediately. You will also see a ready-to-use `mcp_json` block that you can paste directly into your LLM client configuration.

### CLI

```bash
aerostack workspace token create my-workspace --name "CI Bot" --expires-in 86400
```

### Using the `mcp_json` Block

The token creation response includes a ready-to-use configuration block:

```json
{
  "mcpServers": {
    "my-workspace": {
      "url": "https://mcp.aerostack.dev/ws/my-workspace",
      "headers": {
        "Authorization": "Bearer mwt_7a3f9c1e8b4d2f6a..."
      }
    }
  }
}
```

Copy this directly into your Claude Desktop `claude_desktop_config.json`, Cursor MCP settings, or any MCP client configuration. See [Connect via Gateway](/workspaces/gateway-url) for client-specific instructions.

---

## List Tokens

View all tokens for a workspace. The raw token value is never returned -- only metadata.

### Dashboard

Open the workspace and click the **Tokens** tab. Each token shows its name, status, creation date, expiration date, and last used timestamp.

### CLI

```bash
aerostack workspace token list my-workspace
```

### Token Status

A token is **active** when:
- It has not been revoked
- It has not expired

Inactive tokens appear in the list for audit purposes but cannot authenticate requests.

---

## Revoke a Token

Revocation is **immediate**. The token stops working the moment it is revoked -- there is no cache delay.

### Dashboard

Open the workspace, go to **Tokens**, find the token, and click **Revoke**.

### CLI

```bash
aerostack workspace token revoke my-workspace TOKEN_ID
```

  Revoked tokens are permanently deactivated. They remain in the token list for audit purposes but can never be reused.

---

## Token Expiry

Set tokens to expire automatically by providing an expiration duration when creating them.

| Use Case | Recommended Expiry |
|----------|-------------------|
| Personal IDE (Cursor, Claude Desktop) | No expiry or 90 days |
| CI/CD pipeline | 24 hours (`86400` seconds) |
| Shared team token | 30 days (`2592000` seconds) |
| Demo or trial | 1 hour (`3600` seconds) |
| Bot deployment | No expiry |

Expired tokens automatically stop working. They appear in the token list with an inactive status.

---

## Security Best Practices

### One Token Per Client

Issue a separate token for each LLM client, team member, or integration. This way you can revoke one without disrupting others.

```bash
aerostack workspace token create work --name "Alice Cursor"
aerostack workspace token create work --name "Bob Claude Desktop"
aerostack workspace token create work --name "CI Pipeline"
aerostack workspace token create work --name "Support Bot"
```

### Rotate Tokens Regularly

For production integrations, rotate tokens periodically:

1. Create a new token
2. Update your client configuration
3. Verify the new token works
4. Revoke the old token

### Never Commit Tokens

Add `mwt_*` patterns to your `.gitignore`. Workspace tokens grant access to all tools in the workspace, which may include servers with elevated permissions (database access, payment processing, etc.).

  If you accidentally expose a token, revoke it immediately from the dashboard. Revocation takes effect in real-time -- there is no propagation delay.

---

## Per-Token Rate Limiting

Each workspace token is rate-limited to **120 requests per minute**. This limit applies per token, not per workspace.

If you need higher throughput:
- Issue multiple tokens and distribute requests across them
- Use separate workspaces for high-volume and low-volume tools

When the rate limit is exceeded, the gateway returns HTTP 429:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "Rate limit exceeded"
  }
}
```

---

## Per-Member Tokens

When you [invite team members](/workspaces/members) to a workspace, each member gets their own token. This provides:

- **Individual rate limits** -- one member's heavy usage does not affect others
- **Per-member analytics** -- see which member is calling which tools
- **Granular revocation** -- remove one person's access without affecting the team

See [Team Members](/workspaces/members) for details on inviting members and managing per-member tokens.

---

## Authentication Flow

When you make a gateway request:

1. Send `POST /ws/:slug` with `Authorization: Bearer mwt_...`
2. The gateway SHA-256 hashes the token and looks it up in the database
3. If the hash matches a valid, non-revoked, non-expired token, the workspace configuration is loaded
4. The request is processed and the tool call is routed to the correct upstream server
5. If the token is invalid, the gateway returns HTTP 401