> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gojinko.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API keys

> Get and use API keys (jnk_*) for programmatic access to Jinko.

API keys are the simplest way to authenticate with Jinko. They prefix with `jnk_` and work everywhere, the [SDK](/connect/sdk), the [CLI](/connect/cli), MCP clients, and direct [REST](/api-reference/introduction) calls.

Use them for: agents, scripts, CI/CD, server-side apps, MCP clients without OAuth support.

Don't use them for: end-user-facing OAuth flows in MCP clients that support [DCR](/authentication/oauth) (Claude Desktop, ChatGPT, Cursor, Codex, Openclaw).

## Get a key

There are two ways to get a key. If an AI coding agent is doing the work, it can
mint the key itself — it does **not** need a human to visit the dashboard.

<Tabs>
  <Tab title="AI coding agent (MCP)">
    Works with any MCP-capable coding agent — Claude Code, Codex, Cursor, Openclaw,
    Lovable, Replit, opencode, and others. Add the Jinko platform MCP server and call
    its `get_api_key` tool:

    ```
    https://mcp.platform.gojinko.com/mcp
    ```

    Add it the way your agent adds any remote MCP server: a CLI command
    (`claude mcp add --transport http jinko-platform <url>`), an entry in the client's
    MCP config, or — on hosted builders like Lovable and Replit — by pasting the URL
    into their integrations UI.

    The user signs in once through their browser (OAuth). `get_api_key` then bootstraps
    their organization and tenant if they don't exist yet and returns a `jnk_` key,
    together with connection instructions for the REST API, SDK, CLI, and booking MCP.

    <Note>
      **The key you get this way is an ordinary server-to-server key.** Wire it into the
      backend you're building — it is not limited to chat or to the MCP session that
      minted it. There is no need to send the user to the dashboard or to ask them to
      paste a key.
    </Note>

    The same MCP also serves these docs (`search_docs`, `get_doc`, `get_openapi`), so an
    agent can go from "no account" to a working integration without leaving the session.
  </Tab>

  <Tab title="Dashboard (human)">
    <Steps>
      <Step title="Sign in to the dashboard">
        [dashboard.gojinko.com/developers/keys](https://dashboard.gojinko.com/developers/keys)

        First time? You'll be auto-onboarded via Jinko Auth, no waitlist.
      </Step>

      <Step title="Create a key">
        Hit **Create key**, name it something memorable. Default monthly quota is 1,000 requests.
      </Step>

      <Step title="Copy it once">
        The full key is only shown once at creation. Store it somewhere safe (1Password, your secrets manager, etc.) before navigating away.

        If you lose it, just rotate, make a new one and delete the old.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Use a key

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    import { createJinkoClient } from '@gojinko/api-client'
    const client = await createJinkoClient({ apiKey: 'jnk_...' })
    ```

    Or via env: `export JINKO_API_KEY=jnk_...` and call `createJinkoClient()` with no args.
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    # Persist to ~/.jinko/config.yaml
    jinko auth login --key jnk_...

    # Or use an env var (no login needed)
    export JINKO_API_KEY=jnk_...
    jinko flight-calendar --origins CDG --destinations JFK --month 2026-06
    ```
  </Tab>

  <Tab title="MCP (any client)">
    Attach as an `Authorization: Bearer` header on the MCP endpoint:

    ```bash theme={null}
    claude mcp add --transport http jinko https://mcp.builders.gojinko.com/mcp \
      --header "Authorization: Bearer jnk_..."
    ```

    See [Connect via API key](/quickstart#connect-via-api-key) for client-specific configs.
  </Tab>

  <Tab title="REST (curl / any HTTP client)">
    ```bash theme={null}
    curl https://api.gojinko.com/v1/flight_search \
      -H "X-API-Key: jnk_..." \
      -H "Content-Type: application/json" \
      -d '{ "origin": "JFK", "destination": "CDG", "trip_type": "oneway", "departure_date": "2026-06-15" }'
    ```

    The REST API accepts both `X-API-Key: jnk_...` and `Authorization: Bearer jnk_...`. A `jnk_` key is one of two auth methods on every `/v1` route; the other is [WorkOS OAuth](/authentication/oauth) via `Authorization: Bearer <oauth_token>`.
  </Tab>
</Tabs>

## Sandbox keys

Jinko runs two isolated environments: **production** and **sandbox** (test the full flow without touching prod data). They use **separate keys**: a `jnk_` key is scoped to the environment it was created in and won't authenticate against the other. Generate a sandbox key from the dashboard, then point your client at the matching base URL:

| Surface    | Production                             | Sandbox                                        |
| ---------- | -------------------------------------- | ---------------------------------------------- |
| REST / SDK | `https://api.gojinko.com`              | `https://api.sandbox.gojinko.com`              |
| MCP        | `https://mcp.builders.gojinko.com/mcp` | `https://mcp.builders.sandbox.gojinko.com/mcp` |
| CLI        | default                                | `--env sandbox`                                |

The [CLI](/connect/cli#environments-prod-sandbox) and [SDK](/connect/sdk#environments-prod-sandbox) have built-in environment switching (they store the two keys separately); for REST/MCP just use the sandbox URL above with your sandbox key.

## Rotation

If a key leaks (committed to git, posted in chat, etc.):

1. Create a new key in the dashboard.
2. Update your scripts / env / config to use the new key.
3. Delete the old key in the dashboard. **Anything still using it stops working immediately.**

Always rotate; never edit a key in place. There's no rate-limited grace period.

## Quotas

Free tier: 1,000 requests / 30 days, per key. Quota counters are per key, splitting work across multiple keys doesn't help.

Need more? Email [dev@gojinko.com](mailto:dev@gojinko.com) with your use case and we'll bump it.

## Common failures

| Symptom                                | Likely cause                                                       | Fix                                                                                 |
| -------------------------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| `401 Unauthorized`                     | Key missing, mistyped, or revoked                                  | Verify the key in the dashboard; check for whitespace at start/end                  |
| `401` with `unexpected iss claim`      | You're sending a CLI **OAuth** token, not an API key               | Use a `jnk_*` key instead, see [OAuth](/authentication/oauth) for why               |
| `429 Too Many Requests`                | Monthly quota exhausted                                            | Email [dev@gojinko.com](mailto:dev@gojinko.com) or wait for the next billing window |
| `403 Forbidden` on a specific endpoint | Endpoint requires a higher tier or a permission your account lacks | Check the dashboard for plan info; reach out if surprised                           |

For `4xx` debugging, also check the response body, Jinko returns a structured `error` object with a code and message. See [Errors & troubleshooting](/concepts/errors).