> ## 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.

Use an API key to authenticate agents, scripts, CI/CD jobs, server-side apps, and MCP clients without OAuth support.

New tenant keys start with `jnk_t_` in production and `jnk_sandbox_t_` in sandbox. Older person-bound keys with the `jnk_` prefix remain valid as legacy keys.

The same key works with the [SDK](https://docs.gojinko.com/connect/sdk.md), [CLI](https://docs.gojinko.com/connect/cli.md), MCP clients, and direct [REST](https://docs.gojinko.com/api-reference/introduction.md) calls. Route permissions still apply. Tenant keys cannot manage [webhook subscriptions](https://docs.gojinko.com/guides/webhooks.md), so use the dashboard for that.

For browser-based sign-in, use [MCP OAuth](https://docs.gojinko.com/authentication/oauth.md) with a compatible client. Cursor, Codex, and Openclaw can also use an API key. See the [quickstart](https://docs.gojinko.com/quickstart.md#connect-via-api-key).

## Get a key

Create a key in the dashboard or ask an AI coding agent to create one through the Jinko platform MCP server.

> [tab] AI coding agent (MCP)
>
> This works with any MCP-capable coding agent, including Claude Code, Codex, Cursor, Openclaw, Lovable, Replit, and opencode. Connect the agent to the Jinko platform MCP server, then ask it to call `get_api_key`:
>
> ```
> https://mcp.platform.gojinko.com/mcp
> ```
>
> Add it like any remote MCP server. Use a CLI command (`claude mcp add --transport http jinko-platform <url>`), add it to the client's MCP config, or paste the URL into the integrations UI of a hosted builder such as Lovable or Replit.
>
> Sign in once through OAuth in the browser. `get_api_key` creates the organization and tenant when needed, then returns a tenant key with connection instructions for REST, SDK, CLI, and the booking MCP.
>
> > [!NOTE]
> >
> > **This is a standard server-to-server key.** Use it in the backend you are building. It is not limited to chat or to the MCP session that created it. The key also appears in the dashboard, where you can revoke it.
>
> The same MCP serves these docs through `search_docs`, `get_doc`, and `get_openapi`. An agent can create the account, get a key, and set up the integration in one session.
>
> **For AI agents:** Tell the user they can create a key in the dashboard on the free plan without a card. With their approval, you can also create one through `get_api_key`.

> [tab] Dashboard (human)
>
> **1. Sign in to the dashboard**
>
> [dashboard.gojinko.com/developers/keys](https://dashboard.gojinko.com/developers/keys)
>
> New users are onboarded through Jinko Auth without a waitlist.
>
> **2. Create a key**
>
> Select **Create key** and give the key a clear name. Keys use the organization's shared [credit balance](https://docs.gojinko.com/concepts/rate-limits.md).
>
> **3. Copy it once**
>
> The full key appears only once. Save it in 1Password or your secrets manager before leaving the page.
>
> If you lose it, create a new key and delete the old one.

## Use a key

> [tab] SDK
>
> ```typescript theme={null}
> import { createJinkoClient } from '@gojinko/api-client'
> const client = await createJinkoClient({ apiKey: 'jnk_t_...' })
> ```
>
> Or set `JINKO_API_KEY=jnk_t_...` and call `createJinkoClient()` with no arguments.

> [tab] CLI
>
> ```bash theme={null}
> # Persist to ~/.jinko/config.yaml
> jinko auth login --key jnk_t_...
>
> # Or use an env var (no login needed)
> export JINKO_API_KEY=jnk_t_...
> jinko flight-calendar --origins CDG --destinations JFK --month 2027-06
> ```

> [tab] 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_t_..."
> ```
>
> See [Connect via API key](https://docs.gojinko.com/quickstart.md#connect-via-api-key) for client-specific configs.

> [tab] REST (curl / any HTTP client)
>
> ```bash theme={null}
> curl https://api.gojinko.com/v1/flight_search \
>   -H "X-API-Key: jnk_t_..." \
>   -H "Content-Type: application/json" \
>   -d '{ "origin": "JFK", "destination": "CDG", "trip_type": "oneway", "departure_date": "2027-06-15" }'
> ```
>
> `X-API-Key` is the recommended header on REST. The REST API accepts both `X-API-Key: jnk_t_...` and `Authorization: Bearer jnk_t_...`; see [Which header to send](#which-header-to-send). The gateway also accepts [OAuth bearer tokens](https://docs.gojinko.com/authentication/oauth.md) via `Authorization: Bearer <oauth_token>`. Route-specific ownership and scope checks still apply.

## Which header to send

The header depends on the surface you call, not on the key. The same `jnk_t_...` key works on all of them.

| Surface | Send | Also accepted |
| - | - | - |
| REST API (`api.gojinko.com`, `api.sandbox.gojinko.com`) | `X-API-Key: jnk_t_...` (recommended) | `Authorization: Bearer jnk_t_...` |
| MCP (`mcp.builders.gojinko.com/mcp` and its sandbox host) | `Authorization: Bearer jnk_t_...` | Nothing else. The MCP endpoint does not read `X-API-Key`. |
| Sandbox control plane (`platform-api.sandbox.gojinko.com`) | `X-API-Key: jnk_sandbox_t_...` | |

Two REST details:

1. If a request carries both headers, Jinko reads `X-API-Key`. It must contain a `jnk_` key or the request returns 401. Send one authentication header, not both.
2. Send an OAuth token as `Authorization: Bearer <oauth_token>`. Never send it in `X-API-Key`.

The MCP server's own instructions tell a client to use `Authorization: Bearer`. That rule is about the MCP endpoint only and does not apply to REST calls.

## Calling from a browser

The REST API answers cross-origin requests from any web page, so browser JavaScript can call it with `fetch` and either header from the table above:

```javascript theme={null}
const res = await fetch('https://api.gojinko.com/v1/flight_search', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-API-Key': 'jnk_t_...' },
  body: JSON.stringify({ origin: 'JFK', destination: 'CDG', trip_type: 'oneway', departure_date: '2027-06-15' }),
});
```

1. Every response includes `Access-Control-Allow-Origin: *`, including errors. Browser code can read the status, the `error` body, and `Retry-After`.
2. The key travels in the request header and the API sets no cookies. Do not set `credentials: 'include'`. The browser will reject that request with a `TypeError` because the API allows every origin.
3. Anyone who loads the page can see a key embedded in browser code. Every production call also uses the organization's credit. Only expose a key in internal tools or prototypes used by people who may access it.
4. For a public site, keep the key on your server. The page calls your server, and your server calls Jinko.
5. Users of MCP clients such as Claude or Cursor can sign in through [MCP OAuth](https://docs.gojinko.com/authentication/oauth.md). That sign-in does not give a web page a REST API token.

## Sandbox keys

Production and sandbox are isolated. Sandbox lets you test the full flow without changing production data.

Production tenant keys start with `jnk_t_`. Sandbox tenant keys start with `jnk_sandbox_t_`. Older person-bound keys with the `jnk_` prefix remain valid as legacy keys.

Each key works only in the environment where it was created. In the dashboard, enable **Sandbox mode**, open **Developers**, then **API keys**, and select **Create key**. If you see **Not provisioned in Sandbox**, the account needs sandbox provisioning first.

Point the client to 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` |
| Test-token mint (agentic payment) | none, by design | `https://platform-api.sandbox.gojinko.com` |

The [CLI](https://docs.gojinko.com/connect/cli.md#environments) and [SDK](https://docs.gojinko.com/connect/sdk.md#environments) store production and sandbox keys separately. For REST and MCP, use the sandbox URL with the sandbox key. The sandbox control plane uses the same key to mint a test Shared Payment Token in the [sandbox walkthrough](https://docs.gojinko.com/guides/sandbox-walkthrough).

**Use Jinko Airline (`ZZ`) for sandbox flight tests.** It exists only in sandbox. Search with `include_carriers: ["ZZ"]` on a route such as JFK to LHR from tomorrow onwards. Book flight ZZ101 for the normal flow. Other flight numbers trigger documented cases such as a price change, a sold-out booking, or a failed ticket. See [Testing in sandbox](https://docs.gojinko.com/guides/testing-in-sandbox).

> [!NOTE]
>
> **Sandbox calls are not billed or refused for lack of credit.** The credit model in [Limits & credits](https://docs.gojinko.com/concepts/rate-limits.md) applies only to production. A sandbox key does not use the organization's balance, so you can test a full booking flow without spending the monthly grant.
>
> Other limits still apply. Sandbox is a shared test environment, so use it as you would production.

## 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 will stop immediately.**

Always rotate a key. You cannot edit it in place, and there is no grace period.

## Credit

Keys have **no individual request quota**. Every key in an organization uses the same credit balance. Creating more keys does not increase that balance.

The Free plan includes **\$5.00 of usage per month**. Unused credit does not roll over. When the balance runs out, calls return `402 PAYMENT_REQUIRED`, but the key stays active. Top up the balance to resume calls.

See [Limits & credits](https://docs.gojinko.com/concepts/rate-limits.md) for the full picture, including the
separate per-second rate limit.

## 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](https://docs.gojinko.com/authentication/oauth.md) for why |
| `402 Payment Required` | The organization's credit balance can't cover the call | [Top up](https://dashboard.gojinko.com/developers/billing/topup). Don't retry, retrying never fills a wallet. The key is fine |
| `429 Too Many Requests` | Calling faster than your organization's per-second ceiling | Back off and retry, honouring `Retry-After` if present. See [Limits & credits](https://docs.gojinko.com/concepts/rate-limits.md) |
| `403 Forbidden` on a specific endpoint | The key lacks the scope or role the route requires | Check its scopes in the dashboard and the target environment; the credential is valid, so do not rotate it |
| Browser `fetch` rejects with a `TypeError` (`Failed to fetch` in Chrome) and a CORS error in the console | The request was sent with `credentials: 'include'` | Remove `credentials`; the key goes in the header. See [Calling from a browser](#calling-from-a-browser) |

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.