Get API key
Getting started

Authentication

One API key authenticates every surface — REST, MCP and the agent CLI. Here is where keys come from, which headers the server accepts, and how to keep a key out of your repository.

Getting a key

Keys are created in the dashboard under API keys. The full value is shown once, at creation — after that only a prefix is displayed, so copy it into your environment straight away.

terminal
export IMAGEMCP_API_KEY="sk-img-gen-…"

# Optional: point at a different backend (self-hosted, staging)
export IMAGEMCP_API_URL="https://api.imagemcpserver.com"

Accepted headers

Every authenticated endpoint reads the same two headers. Authorization is checked first and x-api-key is the fallback; the Bearer prefix is optional on both.

Request headers

FieldTypeDescription
AuthorizationrequiredstringBearer <IMAGEMCP_API_KEY>. The conventional choice for HTTP clients.
x-api-keystringAlternative to Authorization, useful for MCP clients that pass a bare header value.
Content-Typerequiredstringapplication/json on every POST. Requests are JSON, never form-encoded.

Every /v1 endpoint needs a key

The two discovery routes are the exception: GET /v1 and GET /v1/openapi.json describe the API to anyone. GET /v1/models, GET /v1/me and GET /v1/usage need a key but are free to call; everything that touches a model needs a key and a positive balance.

Auth per surface

The same key authenticates all three ways of reaching the server.

  • REST — send the header on every request.
  • MCP — the key is set once in your client config, either as an IMAGEMCP_API_KEY env var for a local server process or as an x-api-key header for the remote endpoint.
  • Agent skill CLI — export IMAGEMCP_API_KEY in the shell, or run the CLI setup command once to store it.
MCP client config (remote endpoint)
{
  "mcpServers": {
    "imagemcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.imagemcpserver.com/mcp",
        "--header",
        "x-api-key:${IMAGEMCP_API_KEY}"
      ]
    }
  }
}

When auth fails

A missing or invalid key returns 401. A key that is valid but belongs to an account without enough credits returns 400 with the shortfall spelled out, which is the response an agent should surface to the user rather than retry.

400 — insufficient credits
{
  "success": false,
  "message": "Insufficient credits. You need 15 credits, but only have 4 credits available.",
  "currentCredits": 4,
  "requiredCredits": 15
}

On /v1 the failure also carries a typed error object — error.type is authentication_error and error.code is missing_api_key or invalid_api_key, so a client can tell "you sent nothing" apart from "you sent something wrong" without parsing prose. A revoked key answers 401, never 403.

Full status-code table on the errors page.

Keeping keys safe

  • Keep keys in environment variables or a secrets manager — never in source control.
  • Never ship a key in browser or mobile code; anything reachable from a client can be read by anyone.
  • Use a separate key per environment so you can revoke staging without touching production.
  • Rotate by creating the new key first, switching over, then deleting the old one.

A key is a spending credential

Anyone with your key can spend your credits. If one leaks, delete it in the dashboard immediately — deletion takes effect on the next request.

FAQ

Which header should I use, Authorization or x-api-key?

Either works. The server reads Authorization first and falls back to x-api-key, and the Bearer prefix is optional on both. Authorization: Bearer <key> is the conventional choice.

Can I use one key for MCP and REST at the same time?

Yes. A key is scoped to your account, not to a protocol, so the same key works in an MCP client, in the CLI, and in your own HTTP code — all drawing on one credit balance.

What happens if my key leaks?

Delete it in the dashboard and create a new one. Anyone holding a key can spend your credits, so treat it like a password: environment variables only, never committed, never in client-side code.