Organizations and Workspaces

Structuring your team on AI Studio

As long as you work alone, a single API key is enough. Trouble starts the moment three developers share the same account: no one knows which key powers which app, the bill arrives as one indecipherable block, and the day someone leaves the team you have to revoke everything. AI Studio solves this with a two-level architecture: Organizations and Workspaces. Understanding this structure is essential for managing billing, permissions, and resource isolation.

The Organization / Workspace model

The Organization sits at the top of the hierarchy. It is created automatically when you sign up and represents your entity—company, team, or department. This is where everything consolidates: billing, which aggregates all costs; subscription tier selection (Experiment, Scale, or Enterprise); usage limits, meaning global token and request quotas; and member allocation, including invitations and seat management. Creating a new organization requires only a name and acceptance of the terms of service, and nothing prevents a single user from belonging to multiple organizations at once.

Workspaces are subsets within an Organization, designed to segment access and costs by project, team, or environment. Each workspace isolates its API keys, which grant access only to its own resources, and shares fine-tuned models and training datasets among its members. Consumption remains traceable workspace by workspace, so you can say precisely how much the support chatbot costs compared to the internal search engine.

Managing roles and permissions

Three roles coexist at the Organization level, with deliberately distinct scopes.

Remember the middle row: an Admin manages teams and workspaces but never touches billing. This lets you hand technical administration to an ML lead without giving them access to the company credit card.

Creating a workspace therefore requires Admin permissions. From your organization’s Admin page:

1. Go to the Workspaces section
2. Click Create Workspace
3. Give it a descriptive name (for example: production, staging, research)
4. Configure initial permissions

Adding a collaborator follows a similar logic:

1. Go to Admin > Members
2. Click Invite
3. Enter the collaborator’s email address
4. Assign a role (Admin, Member)
5. Select the workspaces they will have access to

Organizational best practices

The first rule is to separate environments. Create at least two workspaces, ideally three, to isolate what happens in development from what touches your users.

Organization "MaStartup"
├── Workspace "development"    → dev API keys, reduced quotas
├── Workspace "staging"        → integration tests
└── Workspace "production"     → prod API keys, high quotas

This separation prevents an infinite loop written on a Friday night in development from devouring production quotas, and it makes cost tracking by environment immediately readable.

Next comes key rotation. Since each key is tied to a workspace, replacing one without interrupting service requires a specific order: generate the new key in the relevant workspace, deploy it in your application, verify that requests actually go through with it, and only then delete the old one. Reversing the last two steps guarantees an outage.

import os

# Best practice: API key via environment variable
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

A key hard-coded in source code will always end up in a Git repository, then in that repository’s history, where it will survive all your cleanup attempts. Use an environment variable from the very first line.

In large organizations, governance also benefits from having one workspace per functional team—data science, backend, product—plus a dedicated workspace for fine-tuning that centralizes datasets instead of letting them duplicate. Explicit workspace names make monthly reporting that much easier.

Concrete scenario: setup

Let’s take a fifteen-person company adopting Mistral. The CTO creates the Organization and subscribes to the Scale tier, then opens three workspaces: dev, staging, and prod. Developers receive Member access limited to the dev workspace, while the ML lead gets Admin access to all three. Each workspace has its own API keys, isolated from one another, so a leaked development key compromises nothing in production.

The admin dashboard, accessible at admin.mistral.ai, then displays consumption by workspace. This is the table the CTO will open at month-end to allocate costs by project, without having to instrument anything in the code.

Key takeaways

• The Organization is the level for billing and global management
• Workspaces isolate API keys, fine-tuned models, and costs
• Always separate development, staging, and production into distinct workspaces
• Store API keys in environment variables, never in code
• The admin dashboard lets you track consumption by workspace in real time