Getting a Mistral API key is short: create an account, open the console, click create once, and you have a secret string. What usually goes wrong is everything after that — which workspace the key belongs to, which connectors it can reach, where it should be stored, when it should be rotated, and why a correctly copied key still returns 401.

This guide follows the actual order of operations and explains key creation, permissions, environment variables, rotation, and 401 debugging. It also covers the difference between an official key and a ZSQH AI Gateway key.

Note: Mistral, Mistral AI, and related model names are trademarks of Mistral AI. This article is independent and not affiliated with Mistral AI. It reflects public documentation and common practice as of October 2026; quotas, permissions, and product shapes may change, so refer to the official console and our model pricing page.

1. Official keys and gateway keys cannot be mixed

There are two common sources of a Mistral API key.

The first is a key created in the official Mistral console, used with the official endpoint https://api.mistral.ai/v1. The second is a key created in the ZSQH AI Gateway console, used with the gateway endpoint https://ai.zhongshangqihang.com/v1.

The two key formats may look similar, but they belong to different systems. An official key works only with the official endpoint, and a gateway key works only with the gateway endpoint. Mixing them usually returns 401, so confirm this first when debugging.

2. Register an account and open the console

The official flow runs entirely in the browser:

  1. Open https://console.mistral.ai and register or sign in to a Mistral account.
  2. Complete the required steps, such as email verification, and enter the Studio console.
  3. According to the official documentation, API access is enabled by default on first use and does not require a credit card, but usage and rate limits apply.
  4. In the left navigation, find API Keys.
  5. Click Create new key.
  6. Enter a Name and choose an Expiration and Connector access scope.
  7. Click Create new key again to finish.
  8. Copy the complete key immediately and store it in a password manager or a server-side secrets service.

The most important point: the full key is shown only once, in the success dialog. After you close it, the console will not display the complete value again. If you did not save it, create a new key and delete the old one.

3. How to fill in the three creation options

Name distinguishes purposes and does not affect permissions. Put the environment and application in the name, for example mistral-dev-chat or mistral-prod-batch. A name like "test" becomes impossible to judge a few months later.

Expiration sets the key's lifetime. Administrators can define an expiration policy; when the policy is off, keys can be set to never expire. In practice, giving production keys an explicit end date is safer — quarterly rotation, for example. Do not set every key to permanent just because it is convenient.

Connector access scope has two options:

  • Shared connectors only: the key can access only connectors shared with the current workspace, not connectors private to the creator. The official documentation recommends this for automation.
  • Private and shared connectors: the key can access both the creator's private connectors and shared connectors. Choose this only when private connectors are genuinely required.

After creation, the key's workspace, connector scope, and expiration cannot be edited directly. To change them, create a replacement key and delete the old one. Spending ten extra seconds at creation is easier than migrating later.

4. Workspace and permissions: a key is not a global pass

Mistral keys are workspace-scoped. Each key is bound to the workspace selected at creation, and that workspace's quota, rate limits, and resource scope apply to the key. In other words, the permission boundary depends not only on the key itself but also on its workspace.

Organization administrators can view, create, rotate, and delete keys across workspaces at admin.mistral.ai/organization/api-keys, and can set organization-level expiration policies. Regular developers can manage their own keys from the user menu in Studio or the API Keys page.

The basic security principle is least privilege: if an application only needs shared connectors, do not select private connectors; if a dedicated production key can be created, do not reuse an administrator key. Once an administrator key enters business code, it is hard to contain later.

5. Store the key in environment variables

Never put a key in source code, frontend JavaScript, mobile bundles, or public repositories. Prefer server-side environment variables or a secrets manager that injects values at runtime.

# macOS / Linux: applies only to the current terminal session
export MISTRAL_API_KEY="your-key-here"

# Example .env file in the project root (add .env to .gitignore)
MISTRAL_API_KEY=your-key-here

Reading it in Python:

import os

api_key = os.environ["MISTRAL_API_KEY"]

On Windows PowerShell, use $env:MISTRAL_API_KEY="your-key-here". In production, prefer a cloud Secrets Manager, a Kubernetes Secret, or a similar secrets service instead of keeping a .env file on the server permanently.

When copying a key, avoid trailing spaces or newlines; log only a prefix or a hash fingerprint; route frontend calls through your backend rather than shipping the key to the browser.

6. Rotation and revocation: follow the order

The goal of rotation is to let the new key take over traffic before the old one goes offline, avoiding downtime. Recommended order:

  1. Create a new key in the same workspace and put the rotation date in its name.
  2. Write the new key into the secrets manager or the deployment platform's environment variables.
  3. Deploy the service and confirm that new instances have read the new key.
  4. Verify the new key with a minimal request, then watch error rates and usage for a while.
  5. Once no traffic uses the old key, delete it in the console.
  6. Review recent usage and logs for unexpected calls.

If you suspect a key has leaked, reverse the order: delete or disable the old key first to stop the damage, then create and deploy a new key. The official documentation treats deletion as revocation, and a deleted key stops working immediately. Do not "observe for a while" during a leak; every minute a credential is exposed can generate cost.

7. Debugging 401: identify which failure it is

A 401 means authentication failed, but the cause is not always "the key is wrong." Use this table in order.

Symptom Common cause Action
401 auth failure The request has no Authorization header Add Authorization: Bearer <key>
401 auth failure The key was copied incompletely, with spaces or newlines Copy it again and check for hidden characters
401 auth failure The key expired or was deleted Check its status in the console and create a new one if needed
401 auth failure An official key is paired with the gateway URL, or vice versa The key and base URL must come from the same platform
401 auth failure The request went to the wrong path The official chat path is /v1/chat/completions
403 Forbidden The key's workspace lacks permission for the model or resource Check the workspace, model permissions, and connector scope

Also distinguish neighboring errors: 402 usually relates to billing, such as insufficient balance, a spending cap, or a failed payment; 403 is insufficient permission, not an invalid key; 429 means a rate limit was hit and should be retried with backoff rather than by swapping keys repeatedly. Mixing 401, 402, 403, and 429 together tends to turn a simple problem into a long one.

8. Official direct access or ZSQH Gateway

If you only use Mistral, and both an official account and a payment method work for you, direct official access is the clear choice: console, documentation, and billing are in one place, and the problem boundary is simple.

If you need to call Mistral, Claude, GPT, Gemini, and other models in one project, or want RMB top-ups and a consolidated bill, ZSQH AI Gateway can reduce management overhead. The gateway offers an OpenAI-compatible endpoint; switching models mainly means changing the model field, and the key and URL change as a pair. Available models and billing are listed on the model pricing page. New users can create an account on the sign-up page or go directly to https://ai.zhongshangqihang.com.

Whichever you choose, never put an official key and a gateway key under the same environment variable name. Use MISTRAL_API_KEY and ZSQH_API_KEY separately and select explicitly by endpoint.

9. Seven checks before launch

  • The key exists only on the server; no full value appears in frontend bundles, logs, or repositories.
  • Development, staging, and production use different keys, ideally in different workspaces.
  • Every key has a clear purpose and expiration date.
  • Connector scope follows least privilege; production keys do not use administrator permissions.
  • The account has usage alerts or spending caps so abnormal calls are noticed quickly.
  • Logs retain only key prefixes or fingerprints, never full credentials.
  • There is a clear revocation and rotation process for departures, lost devices, or suspected leaks.

FAQ

Can I get a Mistral API key for free?

According to the official documentation, API access is enabled by default on first use and does not require a credit card, but the Free tier has usage and rate limits. Check the official console for current quotas and limits. Long-term or high-concurrency use generally requires a paid plan.

Can I view the full key again after creating it?

No. The full key is displayed only once in the creation dialog and cannot be retrieved afterward. If you did not save it, create a new key and delete the old one. Store it in a password manager or secrets service immediately.

Can one key be shared by multiple applications?

Technically yes, but it is not recommended. When applications or environments share a key, you cannot tell who made a call during an incident, and you cannot revoke one consumer separately. Split keys by application and environment, at minimum separating test from production.

Does a 401 always mean the key is wrong?

No. A missing key, malformed key, expired key, deleted key, or a request header without Bearer all return 401; a key and base URL from different platforms also often appear as 401. Check the key status first, then the endpoint, then the request headers.

Can an official key be used with the ZSQH Gateway URL?

No. An official key corresponds only to https://api.mistral.ai/v1, and a gateway key corresponds only to https://ai.zhongshangqihang.com/v1. When switching endpoints, change the key and base URL together; mixing them usually returns 401.

Related reading: