Authentication

The open API and the MCP server accept exactly one form of authentication: an API key sent in an HTTP request header. There’s no OAuth and no cookie-based session.

Header format

Authorization: Bearer gdev_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Send exactly one Authorization header per request: the scheme Bearer (case-insensitive), a single space, then the full key.
• API keys start with gdev_ and are 48 characters long. The console list shows the first 12 characters (for example, gdev_Ab3dEfG) so you can tell keys apart.
• The key is accepted only in the header. Keys in URL query parameters or in the request body are ignored, and an undefined body field such as api_key makes the whole request fail with parameter error 1001.

Getting an API key

Create one in the Developer Console → API Keys. The full key is shown only once, when it’s created or rolled; the server stores only a hash of it, so it can’t be retrieved later. If you lose it, roll the key or create a new one.

To create, disable, roll, or delete keys, see Manage API Keys.

What a key can access

An API key calls the API on behalf of the user who created it, within that user’s personal account:

• Billing: all keys, plus Playground requests in the console, share the account’s credit balance and rate limits.
• Retrieving tasks: any valid key can retrieve, by task_id, any task that user has submitted — including tasks submitted with other keys or from the console Playground.
• Listing tasks: the List Tasks endpoint returns only tasks submitted with the key making the request.
• Team accounts: not available yet; keys can only be created under a personal account.

A key can do exactly what the open API offers: list platforms, submit tasks, retrieve tasks, and list tasks. It can’t manage keys, and it can’t access the brand-monitoring data in the MaxAEO product.

Authentication errors

The server re-validates the key on every request: the key must exist, be enabled, not be expired, and belong to a user and account that are still active. If any check fails, the open API returns:

{
  "ret": 1030,
  "msg": "{\"zh\":\"API Key 无效、已停用或已过期\",\"en\":\"The API key is invalid, disabled or expired.\"}"
}

You also get 1030 when the Authorization header is missing, malformed, or sent more than once. For security reasons, 1030 doesn’t say which check failed, so work through this list:

1. Does your environment variable hold the complete key? (Common mistakes: copying only the prefix, or a trailing newline or space.)
2. Is the header written as Authorization: Bearer <key> — not Bearer: <key> or Token <key>?
3. Check the key’s status on the console’s API Keys page. Disabled, expired, and deleted keys are all rejected, and after a roll the old key stops working when its grace period ends.

Note

The HTTP status code is still 200 — check ret in the response body. The MCP server is the exception: an invalid key returns HTTP 401 so MCP clients can prompt you to reconfigure. See Connect via MCP.

What happens to in-flight tasks when a key stops working

After a key is disabled, deleted, or expires:

• New requests with that key are rejected immediately (1030).
• Tasks that were submitted but are still waiting locally (queued) and haven’t been dispatched yet will fail at dispatch with error_code credential_invalid. No credits are charged.
• Tasks already dispatched to the platform finish normally, and you can still retrieve them with another valid key or in the console.

Security best practices

• Use keys on the server only. Never put a key in browser code, mobile apps, mini-programs, browser extensions, or public repositories. Read it from an environment variable or a secrets manager on your server.
• Use separate keys per environment and project — for example “Production”, “Staging”, and “Dashboard”. If one key leaks, you can disable or roll just that key without affecting anything else, and the console breaks down usage by key.
• Set an expiration for short-lived uses. For one-off scripts or contractor access, choose a 30- or 90-day expiration so the key retires itself.
• Rotate regularly, without downtime. Use Roll key to generate a new key and give the old one a grace period (1 hour, 24 hours, or 7 days). Deploy the new key first, then let the old one expire.
• Act immediately if you suspect a leak. Roll the key in the console with the old key set to expire Immediately, or disable it, then check Request Logs for unexpected calls.
• Never log the full key. If you need to identify a key in logs, the first 12 characters are enough.

Related pages

Manage API KeysCreate, disable, roll, and delete keys in the console.

Error HandlingRequest-level error codes beyond 1030, and how to handle them.