Generate a Read‑Only API Key

Preview

The MCP server is currently available on the preview environment only. All URLs below use api-preview.stoxiio.com.

Treat your API key like a password

Your API key provides direct access to your financial data — portfolios, wealth, balances, and more. Never share it publicly, commit it to a repository, or paste it into untrusted tools. If you suspect a key has been compromised, revoke it immediately and create a new one.

Before connecting any AI assistant, you need to create an API key with Read scope. This key gives the MCP server permission to fetch your data without being able to modify anything.

Option A — From the Settings page (recommended)

The easiest way to create and manage API keys is directly from the Stoxiio web app:

Log in to Stoxiio.
Navigate to Settings → API Keys.
Click Create API key.
Fill in:
- Name — a label to identify this key (e.g. MCP - VS Code).
- Permissions — select Read only for MCP usage.
- Expiration — choose an expiration period (90 days recommended) or no expiration.
Click Create.
Copy your key immediately — it will only be shown once.

From the same page you can also view all your keys, see their status and last usage, and revoke any key you no longer need.

Save your key

The full API key is only displayed once at creation time. Store it in a secure location (e.g. a password manager). If you lose it, you'll need to create a new one.

Option B — Via the API

You can also manage API keys programmatically using the REST API.

Step 1 — Authenticate

You need a valid JWT token to manage API keys. Log in through the Stoxiio app or call the authentication endpoint:

POST https://api-preview.stoxiio.com/users/authenticate
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "your_password",
  "rememberMe": false
}

Copy the token from the response — you'll need it in the next step.

Step 2 — Create a Read‑only API Key

Call the API key creation endpoint with your JWT token:

POST https://api-preview.stoxiio.com/api-keys
Content-Type: application/json
Authorization: Bearer <your_jwt_token>

{
  "name": "MCP Read-Only",
  "scope": "Read",
  "expiresInDays": 90
}

Field	Description
`name`	A human‑readable label so you remember what this key is for.
`scope`	Set to `"Read"` for MCP usage. Other values: `"Write"`, `"Read, Write"`.
`expiresInDays`	Optional. Number of days until the key expires. Omit for a non‑expiring key.

The response contains your API key (prefixed with stx_). Copy it now — it will not be shown again.

{
  "id": "a1b2c3d4-...",
  "name": "MCP Read-Only",
  "key": "stx_abc123def456...",
  "scope": "Read",
  "expiresAt": "2026-05-09T00:00:00Z"
}

Save your key

The full API key is only displayed once at creation time. Store it in a secure location (e.g. a password manager). If you lose it, you'll need to create a new one.

Step 3 — Verify the key (optional)

Test that your key works by calling any read endpoint:

GET https://api-preview.stoxiio.com/portfolios
X-Api-Key: stx_abc123def456...
Accept: application/json

You should receive a 200 OK response with your portfolio data.

Managing API keys

Recommended

The easiest way to manage your API keys is from the Stoxiio web app under Settings → API Keys. You can view, create, and revoke keys without needing to call the API directly.

If you prefer to manage keys programmatically, you can use the following API endpoints:

List all keys

GET https://api-preview.stoxiio.com/api-keys
Authorization: Bearer <your_jwt_token>
Accept: application/json

Revoke a key

DELETE https://api-preview.stoxiio.com/api-keys/<key_id>
Authorization: Bearer <your_jwt_token>

Update a key

PUT https://api-preview.stoxiio.com/api-keys/<key_id>
Content-Type: application/json
Authorization: Bearer <your_jwt_token>

{
  "name": "Renamed Key",
  "scope": "Read"
}

Full `.http` file reference

If you use VS Code with the REST Client extension, you can use this .http file for quick API key management:

@HostAddress = https://api-preview.stoxiio.com
@BearerToken = Bearer <your_jwt_token>

### Authenticate
POST {{HostAddress}}/users/authenticate
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "your_password",
  "rememberMe": false
}

### Create Read-Only API Key for MCP
POST {{HostAddress}}/api-keys
Content-Type: application/json
Authorization: {{BearerToken}}

{
  "name": "MCP Read-Only",
  "scope": "Read",
  "expiresInDays": 90
}

### List all API Keys
GET {{HostAddress}}/api-keys
Authorization: {{BearerToken}}
Accept: application/json

### Revoke an API Key
DELETE {{HostAddress}}/api-keys/<key_id>
Authorization: {{BearerToken}}

### Test the key
GET {{HostAddress}}/portfolios
X-Api-Key: stx_<your_key>
Accept: application/json

Best practices

Use Read‑only scope for MCP

The MCP server only needs to read your data — never create a key with Write or Read, Write scope for AI integrations. If a key is compromised, a Read‑only scope limits the blast radius.

Set an expiration date

Always set expiresInDays when creating a key. A 90‑day expiration is a good default. You can create a new key and rotate it before the old one expires.

One key per integration

Create a separate key for each tool or device:

Key name	Used in
`MCP - VS Code work laptop`	VS Code on your work machine
`MCP - Claude Code`	Claude Code CLI
`MCP - Cursor personal`	Cursor on your personal machine

This way, if you need to revoke access for one tool, your other integrations keep working.

Rotate keys regularly

Create a new key with a fresh expiration.
Update your MCP client configuration with the new key.
Verify the new key works.
Revoke the old key.

Never commit keys to version control

If your configuration file contains the API key in plaintext (e.g. .mcp.json for Claude Code), add it to .gitignore:

.mcp.json

For VS Code, the mcp.json configuration uses promptString inputs so the key is never written to disk — this is the safest approach.

Use a password manager

Store your API keys in a password manager (1Password, Bitwarden, etc.) so you can retrieve them when setting up a new device or rotating keys.

Revoke unused keys

Periodically review your keys in Settings → API Keys and revoke any you no longer use. Fewer active keys means a smaller attack surface.

Storing your key securely

Your Stoxiio API key is a secret that grants access to your financial data. Treat it like a password.

VS Code is already secure

VS Code uses a promptString input — the key is entered once and then persisted in VS Code's secure secret storage. It survives restarts and is never written to any config file. No additional steps are needed if you only use VS Code.

Don't leave your key in plaintext

Other MCP clients (Claude Code, Cursor, Windsurf…) store configurations in plaintext JSON files (.mcp.json, ~/.claude.json, .cursor/mcp.json, etc.). Never hardcode your API key in these files — anyone with access to your machine or your repository could read it.

Most MCP clients support referencing environment variables in their config files using ${STOXIIO_API_KEY} syntax. This means you can keep the actual key out of any config file:

{
  "headers": {
    "X-Api-Key": "${STOXIIO_API_KEY}"
  }
}

How you set that environment variable securely is up to you. Here are some directions to explore depending on your OS:

macOS / Linux

Look into your OS keychain or secret manager (e.g. macOS Keychain via the security CLI) to store secrets and export them automatically in your shell profile (~/.zshrc, ~/.bashrc).

Windows

Look into Windows Credential Manager, DPAPI encryption, or user‑level environment variables (via PowerShell or System Settings) to store and retrieve secrets without hardcoding them.

Regardless of how you store your key, add your client's MCP config file to .gitignore as a safety net:

# MCP config files (may contain API keys)
.mcp.json
.cursor/mcp.json

Security summary

Client	Secure by default?	Action needed
VS Code	✅ Yes — key stored in VS Code's secure secret storage	None
Claude Code	❌ No — plaintext in `.mcp.json` / `~/.claude.json`	Use `${STOXIIO_API_KEY}` + secure storage
Cursor	❌ No — plaintext in `.cursor/mcp.json`	Use `${STOXIIO_API_KEY}` + secure storage
Windsurf	❌ No — plaintext in `mcp_config.json`	Use `${STOXIIO_API_KEY}` + secure storage

Option A — From the Settings page (recommended)​

Option B — Via the API​

Step 1 — Authenticate​

Step 2 — Create a Read‑only API Key​

Step 3 — Verify the key (optional)​

Managing API keys​

List all keys​

Revoke a key​

Update a key​

Full .http file reference​

Best practices​

Use Read‑only scope for MCP​

Set an expiration date​

One key per integration​

Rotate keys regularly​

Never commit keys to version control​

Use a password manager​

Revoke unused keys​

Storing your key securely​

Security summary​