A GLM API key is the credential for calling Zhipu's GLM models. It looks like a short string of characters, but it actually determines three things: whether a request passes authentication, which account pays for it, and how much risk a leak creates. Many failed integrations are not model or network problems at all. The key is the wrong type, it is stored the wrong way, or it was created once and never rotated.

This article follows the order "choose a type, create, store, rotate, troubleshoot." It explains both paths to a key, the official Zhipu platform and the ZSQH AI Gateway, and ends with a security checklist you can apply directly.

Note: Zhipu, GLM, and BigModel are trademarks of their respective owners. This article is for technical explanation only and implies no affiliation, agency, or endorsement relationship with Zhipu. Key creation entry points, verification requirements, and billing rules are governed by the official Zhipu open platform documentation.

1. First determine which type of key you need

The Zhipu open platform manages keys for individual plans, team plans, and standard model APIs separately, and they are not interchangeable. Before creating a key, confirm what it is for. Otherwise you can easily end up in a situation where "the key is valid, but calls still fail."

  • Standard model API key: used for backend services, scripts, agents, and batch jobs, billed by actual call volume. Most technical integrations belong in this category.
  • Coding Plan key: used for coding tools such as Claude Code. It draws on plan entitlements and is not suitable for calling general business interfaces.
  • Team or enterprise keys: used for multi-person collaboration and centralized management. Their permissions and billing ownership differ from personal keys.

Using a Coding Plan key against the standard API commonly results in an authentication failure or a message saying the plan does not cover that model. When you see this kind of error, check the product type of the key first, then check whether the key itself was copied in full.

2. Create a key on the Zhipu open platform

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

  1. Open the Zhipu open platform, register, and sign in.
  2. Go to the API Keys page in the console and confirm the current project or workspace.
  3. Click to create a new key, and name it by environment and service, for example prod-customer-service.
  4. Copy the full key and store it immediately in a password manager or a server-side secret manager.
  5. Check the balance or resource-pack status on the billing page so the key is not created but unusable.
  6. Verify the key with one minimal request before writing it into production configuration.

Two cautions. First, the key is usually shown in full only at creation time and may not be viewable again after you close the page. Second, identity verification and enterprise verification requirements change with products and policies, so follow the page prompts and official documentation.

3. Create a key through a gateway

If a team uses several models at once, or wants unified quotas, one bill, and one invoice, it can register with the ZSQH AI Gateway. Open the API keys page, create a key, set a spending cap and an expiry date, then check the model pricing page for available GLM models and how they are billed.

A gateway key is valid only against the ZSQH base URL and cannot be used to call Zhipu's official endpoint. Conversely, an official key cannot be used directly on the gateway. Naming and storing the two sets of keys separately is the simplest approach.

4. Put the key in environment variables

The riskiest approach is writing a key into source code, a frontend bundle, or a chat history. Use environment variables or a secret management service so the code only references a variable name.

# Keep .env local only, and add it to .gitignore
GLM_API_KEY=your_key_here
GLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("GLM_API_KEY"),
    base_url=os.getenv("GLM_BASE_URL"),
)

At minimum, do the following in production: never commit .env to Git; use the cloud provider's Secret Manager, KMS, or container orchestration secrets; use separate encrypted variables in CI/CD; redact the Authorization header in logs; and never let a server-side key appear in frontend code.

5. Permission isolation, rotation, and audit

One key for everything saves effort in the short term and makes diagnosis hard in the long term. Split keys as follows.

Practice Problem it solves Practical advice
Separate test and production Test traffic pollutes billing; accidental deletion Two keys, two quotas
One key per service Cannot trace call origin Name by service or repository
Set spending caps Runaway calls burn budget quickly Configure limits and alerts in the console
Rotate regularly Long-term leak risk Rotate quarterly; revoke immediately on handover
Keep call logs Dispute and incident review Log time, model, and usage; never log the plaintext key

When rotating, do not delete the old key first. Create the new key, shift traffic gradually, confirm that the new key's quota, model permissions, and billing are correct, then revoke the old key. That way you can roll back quickly if the new configuration has a problem.

6. 401 and other common errors

HTTP 401 only says "authentication failed." The specific cause is in the business code in the response body. In Zhipu's official error codes, 1000 means authentication failed, 1001 means the request header is missing authentication information, 1003 means the token has expired, and 1005 means two-factor authentication is enabled on the account. Work through the checks in order:

  1. Confirm the header is Authorization: Bearer <key>, with no extra spaces or quotation marks.
  2. Confirm you copied the complete key and did not mistake the key name or mask for the key itself.
  3. Confirm the key type matches the interface; do not mix standard API keys and plan keys.
  4. Confirm the base URL matches the key's owner: official key with the official address, gateway key with the gateway address.
  5. Confirm the account is in good standing. Arrears return 1113, and rate limiting returns 1302 or 1305.

In addition, 1211 means the model does not exist, usually because the model name is misspelled or the model is not enabled. 1261 means the input is too long, so compress the context or split it into chunks. Putting business codes into logs makes troubleshooting much faster.

7. Pre-launch checklist

  • The key exists only on the server or in a secret management service.
  • Test, production, and CI use different keys.
  • Every key has a spending cap and an owner.
  • Alerts are configured for low balance and sudden usage spikes.
  • Key revocation and replacement have been rehearsed once.
  • Logs contain no full keys, phone numbers, or other sensitive data.
  • Keys are reclaimed when team members leave or hand over work.

8. FAQ

1. Where is a GLM API key created?

Sign in to the Zhipu open platform and create it on the API Keys page in the console. If you use the ZSQH AI Gateway, create it on the API keys page of the gateway console. The two sets of keys are not interchangeable.

2. Can a key be placed in frontend code or a mini program?

No. Frontend code can be viewed by users, and any key written into it should be treated as leaked. The correct pattern is for the frontend to call your own backend, and for the backend to hold the key and forward model calls.

3. Can one key be shared across several projects?

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

4. What should I do if a key leaks?

Revoke or delete the key in the console immediately, create a new key, and update the server configuration. At the same time, check billing and call logs for abnormal usage, and contact platform support if necessary.

5. Can official keys and gateway keys be mixed?

No. Their authentication systems, base URLs, and billing accounts are all different. The most common symptom of mixing them is a 401, followed by requests going to the wrong service address.