Workspaces
A workspace is the unit of ownership in Gyrence. Every API key, every credit balance, and every usage event belongs to exactly one workspace. When you call the API, the key you present is what tells us which workspace to bill and which activity log to write to.
Workspaces are how teams share access without sharing credentials, and how a single person separates unrelated projects — staging vs. production, client A vs. client B — into clean, independently-metered ledgers.
What a workspace owns
- API keys. Minted in the console, scoped to the workspace, revocable at any time. A key never moves between workspaces.
- Credit balance. Fetches, searches, gyres, maps, and extracts draw down the workspace's credits. Top-ups apply to one workspace.
- Usage events. Every billable call is recorded against the workspace, viewable on the Activity and Usage pages.
- Members. Humans who can sign in to the console and see the workspace's keys, usage, and settings.
What a workspace does not own: the data you fetch. Gyrence does not retain fetched page content beyond the response.
Members and roles
Roles control what a member can do inside the console. API keys are not role-scoped — any valid key gives full API access to the workspace it belongs to.
| Role | Can do |
|---|---|
owner | Everything admin can, plus delete the workspace and transfer ownership. Exactly one per workspace. |
admin | Mint and revoke keys, invite members, change settings, view usage. |
member | View usage and activity. Cannot mint keys or invite. |
Switching workspaces
The workspace switcher in the top-right of the console scopes everything below it — keys, usage, activity, settings — to the selected workspace. The switcher is the only place workspace context is set; there is no per-page override.
A signed-in user always has at least one workspace. Personal workspaces are created on first sign-in; team workspaces are created from Settings → Workspaces → New.
Lifecycle
| State | Meaning |
|---|---|
| Active | Keys work, usage accrues, members can sign in. |
| Decommissioned | All keys revoked. History (usage events, member list) is retained. The workspace cannot be re-activated — create a new one. |
Workspaces are never deleted in production. To wind one down, revoke every key and rename it (e.g. acme-prod → acme-prod-decommissioned-2026-05). The historical ledger stays intact for audit and reconciliation.
Usage events are financial records. Deleting a workspace would orphan the events tied to it and break reconciliation against invoices. Revoke-and-rename gives you the same operational outcome without breaking the ledger.
Common patterns
- One workspace per environment.
acme-dev,acme-staging,acme-prod— separate keys, separate credit pools, separate dashboards. The cleanest way to keep staging traffic out of production billing. - One workspace per client. Agencies and consultancies give each client their own workspace so usage and costs map 1:1 to invoices.
- A shared "ops" workspace. For internal monitoring, scraping, or research that isn't tied to a customer-facing product.