Tokens

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

Caution

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.

2. Go to Tokens

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

3. Create Token

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

4. 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

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:

{
  "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 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

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

aerostack workspace token revoke my-workspace TOKEN_ID

Note

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.

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.).

Caution

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:

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

---

Per-Member Tokens

When you invite team 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 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