---
slug: developer-api-authentication-billing
title: Authentication and workspace billing
category: capability
status: published
tags: [api key, authentication, bearer, billing, workspace, workspace binding, task-bound workspace, isolation, 402, cost, budget, 密钥, 计费, 扣费, 付费, 绑定工作区]
aliases: []
lastEditAt: 2026-08-02
---
## Authentication and billing

Every Public Task API request is authorized by one workspace-scoped key, and
that key's workspace is the workspace that pays for the Task it creates.

Create a workspace key through the session-authenticated developer endpoint:

```http
POST /api/developer/api-keys
Content-Type: application/json

{
  "companyId": "<workspace-company-id>",
  "name": "Production backend",
  "scopes": ["tasks:read", "tasks:write", "webhooks:manage"]
}
```

The response shows the raw `tyc_...` token once. Store it as a secret. Tycoon
stores only its SHA-256 hash. Owners and admins can list or revoke keys through
`GET /api/developer/api-keys` and
`DELETE /api/developer/api-keys/{key_id}`.

Every public request uses:

```http
Authorization: Bearer tyc_...
```

The API key's controller workspace is the billing account. Every
Task-attributed model, runtime, media, and connector cost is charged there at
its actual metered cost—even when the Task executes in another workspace.
Creating external work with no available spend authority returns HTTP `402` and
creates no Task. `budget_usd` on a create is a per-Task ceiling, not a payment
or a wallet top-up; omitting it means no per-Task ceiling and does not make
workspace usage free.

Tycoon's own evaluation keys use a server-only scope that customers cannot
mint. Those Tasks can run with a zero wallet balance, but token and cost usage
is still recorded in full; the workspace wallet is not debited.

## Choose where future Tasks execute

Omit `workspace_id` when creating a Task to get a new, real task-bound
workspace. It starts with the normal Astra/team/Company Brain seed, but does
not receive welcome credit or a separate subscription. It is the default for a
one-off outcome: its memory and context are isolated from every other API Task.

To continue work in an existing workspace, bind it to this specific API key
once. The key's user must currently be an `OWNER` or `ADMIN` of that workspace:

```bash
curl -sS -X POST https://tycoon.us/api/public/workspaces/<workspace-id>/bind \
  -H "Authorization: Bearer $TYCOON_API_KEY"
```

```json
{
  "workspace": {
    "id": "cm...",
    "name": "Growth",
    "slug": "growth",
    "task_bound": false
  },
  "bound": true
}
```

Binding affects only future creates. It does not move Tasks, memory, results,
or costs that already exist. A bound workspace is still rechecked at each
create; if the user is demoted or the binding is absent, the API returns the
same non-disclosing `404` as an unknown workspace.

Published-method keys always use a new isolated task-bound workspace. They
cannot bind or reuse a seller workspace, so a customer never receives the
seller's workspace memory, data, connectors, or standing authority.

## Next steps

- [Quickstart: create your first Task](/help/developer-api-quickstart)
- [Publish a workspace method as an API](/help/developer-api-published-method)
- [Create and read Tasks](/help/developer-api-create-read-tasks)
- [Idempotency, retries, errors, and limits](/help/developer-api-reliability-errors)