A Qwen API key is the credential used to call Tongyi Qianwen models. It is more than a string of characters acting as a password: whether a request passes authentication, which account is billed, and how quickly you can locate a problem all depend on the key's type and ownership. Qwen keys are also bound to two additional dimensions — region and workspace — which is the root cause of many cases where "the key is obviously entered correctly but the API returns 401."

This article follows the sequence "understand ownership — create — configure permissions — store in variables — troubleshoot — rotate," and explains both the Alibaba Cloud Model Studio path and the ZSQH AI Gateway path.

Note: Qwen, Tongyi Qianwen, Alibaba Cloud, Model Studio (Bailian), and DashScope are trademarks or product names of Alibaba Group and its affiliates. This article is for technical explanation only and implies no affiliation, agency, or endorsement relationship with Alibaba Group. The creation entry point, permission rules, and billing standards are subject to the official Alibaba Cloud Model Studio documentation and console.

1. First understand the key's three-layer ownership

In Model Studio, a single key belongs to three dimensions at the same time:

  • Account: it can belong to the Alibaba Cloud primary account or to a RAM user.
  • Region: Beijing, Singapore, US Virginia, Hong Kong (China), and other regions are independent of one another.
  • Workspace: the default workspace or a sub-workspace determines which models the key can call.

If any one of these three dimensions does not match, the result appears as an authentication failure or insufficient permission. Region deserves particular attention: each region has its own endpoint domain, API keys, and model list, and a key cannot be used across regions. Using a key created in Beijing to request a Singapore address usually returns 401 with invalid_api_key, but that does not mean the key itself is invalid.

2. Create an API key in Alibaba Cloud Model Studio

The official path suits teams that use only Qwen and want new models and capabilities as soon as they become available. The basic steps are:

  1. Sign in to the Alibaba Cloud Model Studio console and select the correct region in the upper-right corner.
  2. Open the API Key page and click "Create API Key."
  3. Choose the owning account: the Alibaba Cloud primary account by default, or a specific RAM user.
  4. Choose the owning workspace: the default workspace is fine for a quick start; choose a sub-workspace when you need to isolate models or costs.
  5. Set permissions: "All" is recommended first; when you need to tighten access, choose "Custom" and configure an IP allowlist and the accessible model scope.
  6. After creation, immediately copy the full key and the API host shown on the page, and store them in a password manager or a server-side secrets management system.
  7. Verify authentication, region, and model name with one minimal request before writing the key into your production configuration.

Two details are easy to overlook. First, creating a key requires super-administrator or workspace-administrator permission, so ordinary members may not see the create button. Second, the plaintext key is usually shown in full only once at creation and cannot be viewed again after the dialog closes; if you did not save it, you can only reset or create a new one. Long-lived keys do not expire automatically, but "does not expire" does not mean "does not need rotation."

3. Workspaces, RAM, and permission boundaries

The workspace is the core of Model Studio's permission model. A key in the default workspace can call the standard models in that workspace; a key in a sub-workspace can call only the models that workspace has been granted. If you have deployed a fine-tuned model, you must use a key from the workspace where the model resides, otherwise you will encounter "the model exists but access is denied."

Rules related to RAM users deserve extra care:

  • A key can belong to a RAM user, and the account format is usually username@<AccountAlias>.onaliyun.com.
  • If you delete that user or role in the RAM console, the keys under its name become invalid immediately and cannot be recovered.
  • If you remove a RAM user from a workspace, its key becomes invalid; adding the user back restores it.

Custom permissions suit production environments: use an IP allowlist to restrict sources and a model scope to restrict which models can be called. IP allowlists support IPv4 and IPv6, but IPv6 is currently supported only in the Beijing region, while US regions support IPv4 only; the exact entry limit is subject to the console. Package-type keys (for example, keys beginning with sk-sp-) and general-purpose API keys are two separate systems, so do not use a package key with a general-purpose Base URL.

4. Put the key in an environment variable

The most dangerous practice is writing a key into source code, a front-end bundle, notebook output, or a chat log. Model Studio's conventional environment variable name is DASHSCOPE_API_KEY, and code should reference only the variable name:

# Local .env file; remember to add it to .gitignore
DASHSCOPE_API_KEY=your_key_here

# Effective temporarily in the current terminal
export DASHSCOPE_API_KEY="your_key_here"

# Minimal verification: confirm the key, region, and model name match
curl https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3.8-max","messages":[{"role":"user","content":"ping"}]}'

In production, do at least the following: never commit .env to Git; use a cloud Secret Manager, KMS, or container secrets; use separate variables in CI/CD; mask the Authorization header in logs; and never let the front end hold a server-side key. Note that model names and prices in examples change between versions; the actual names and billing are subject to the console's model list and the model pricing page.

5. Choosing between an official key and a gateway key

If your team uses only Qwen, an official key is the most direct option. If you also use DeepSeek, GLM, Kimi, and other models, or want unified quota, billing, and invoices, you can create a key on the ZSQH AI Gateway. The two are not substitutes for each other; they are two management approaches.

Dimension Alibaba Cloud Model Studio official key ZSQH AI Gateway key
Creation entry Model Studio console Gateway console
Scope Qwen and third-party models within the Model Studio region Multiple models enabled on the gateway
Billing account Alibaba Cloud account Gateway account
Base URL Model Studio addresses such as dashscope.aliyuncs.com https://ai.zhongshangqihang.com/v1
Suitable scenario Qwen only, newest models Multi-model access and unified billing

The authentication systems of the two key types differ and cannot be mixed: an official key goes with the official Base URL, and a gateway key goes with the gateway Base URL. The most common symptom of mixing them is 401, followed by requests being sent to the wrong region or service.

6. 401 troubleshooting: check the region first, then the request header

When you hit a 401, do not rush to reinstall the SDK. Work through this order:

  1. Is the request header Authorization: Bearer <key>, with exactly one space after Bearer?
  2. Was the key copied in full, without newlines, quotes, or leading or trailing spaces?
  3. Does the key's creation region match the region of the Base URL?
  4. Does the workspace match? A workspace-specific domain accepts only keys from that workspace.
  5. Has the key been disabled, deleted, or reset? Has the creating RAM user been removed from the workspace or deleted?
  6. Are you using a package key beginning with sk-sp- against a general-purpose endpoint?
  7. Is the account in arrears? Arrears usually return 400 with Arrearage, not 401, but they also show up as "the API will not respond."

If all of the above are normal, record the Request ID in the response and look it up in the console's call logs or model monitoring. The Request ID is the most useful piece of information when filing a support ticket — far more useful than saying "it returned an error."

7. Rotation, revocation, and audit

Using one key everywhere saves effort in the short term but makes troubleshooting hard in the long term. Split keys by environment and service at minimum: one each for testing, production, and CI; one per back-end service; and names that include the environment and service, such as prod-customer-service. Pair this with spending limits and usage alerts so abnormal calls are discovered before they burn through a large amount of credit.

When rotating, do not delete the old key directly. The correct order is: create a new key → shift a small amount of traffic gradually → confirm that model permissions, quota, and billing are normal → revoke the old key. This way, if the new configuration has a problem, you can roll back quickly. When a team member leaves, an outsourcing handover occurs, or a key has appeared in logs or a public repository, revoke and recreate it immediately, and check billing and call records for anomalies.

8. Frequently asked questions (FAQ)

1. Where do I create a Qwen API key?

Sign in to the Alibaba Cloud Model Studio console, select a region, and create the key on the API Key page. If you use the ZSQH AI Gateway, create it in the gateway console; the two key systems are not interchangeable.

2. Why does a valid key return 401?

The most common cause is a region mismatch, followed by incomplete key copying, an incorrect request header format, a workspace mismatch, or a deleted creating RAM user. First check whether the key and Base URL belong to the same region, then inspect the request header.

3. Can one key be shared across multiple projects?

Technically yes, but it is not recommended. A shared key cannot distinguish call sources, one leak affects every business, and billing is hard to allocate. Split keys at least by environment and core service.

4. What should I do if a key leaks?

Immediately disable or delete the key in the console, create a new key, and update the server configuration. Check billing and call logs for abnormal usage, and contact platform support to explain the situation if necessary. Do not just change the code without revoking the old key.

5. Can official keys and gateway keys be mixed?

No. Their authentication systems, Base URLs, and billing accounts are all different. Mixing them usually returns 401 and may also send requests to the wrong service address.