# Jinko for AI agents

Jinko is a travel API: flights, hotels and cars, with search, pricing and booking. This page lists what an AI agent needs on this environment after registering with the steps in [auth.md](https://dashboard.gojinko.com/auth.md), which WorkOS generates.

## Hosts on this environment

| What | Value |
|---|---|
| Agent identity issuer (`ISSUER` in auth.md) | `https://auth.gojinko.com` |
| Token `resource` the Jinko platform accepts (`RESOURCE` in auth.md step 4) | `https://mcp.platform.gojinko.com` |
| Jinko Platform MCP (Streamable HTTP) | `https://mcp.platform.gojinko.com/mcp` |
| Travel REST API (keys from `environment: production`) | `https://api.gojinko.com` |
| Travel MCP (same keys) | `https://mcp.builders.gojinko.com/mcp` |
| Dashboard, where a person claims the organization | `https://dashboard.gojinko.com` |

## From an agent token to an API key

- The Jinko platform accepts agent access tokens whose audience is `https://mcp.platform.gojinko.com`: the token auth.md step 4 returns when `RESOURCE` is `https://mcp.platform.gojinko.com`. A token with another audience, including the default one issued when `RESOURCE` is omitted, is refused.
- The Platform MCP at `https://mcp.platform.gojinko.com/mcp` is a standard MCP server: JSON-RPC over Streamable HTTP with `Authorization: Bearer <access token>`, an `initialize` request, then `tools/call`. Requests carry `Accept: application/json, text/event-stream`, and responses arrive as server-sent events (`data: {…}` lines). On this deployment the `initialize` response carries an `Mcp-Session-Id` header, set by the hosting gateway; later requests repeat it, and a `tools/call` without it gets `400`. A `notifications/initialized` message is accepted but not required.
- Its `get_api_key` tool takes `key_name` (a label) and `environment`. `environment` is `production` for agent registrations: it mints a key for this environment's travel API (`https://api.gojinko.com`), whatever the environment is called. Sandbox keys aren't available to agent registrations. The first call creates the agent's Jinko organization and a default tenant. The tool result's text is a JSON object that carries the API key once (`api_key`, a `jnk_t_…` value) and `how_to_connect` with this environment's hosts.
- Its `whoami` tool returns the agent's organization and claim status.
- Example `tools/call` body: `{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_api_key","arguments":{"key_name":"my-agent","environment":"production"}}}`

## What the key is for

- The API key, not the agent token, authenticates travel calls. Agent tokens are refused on the travel API.
- REST: `https://api.gojinko.com` with the header `X-API-Key: <key>`. Example: `POST https://api.gojinko.com/v1/flight_search` with `{"origin":"JFK","destination":"LAX","destination_type":"airport","departure_date":"YYYY-MM-DD","trip_type":"oneway","adults":1}`. An untyped code that a city shares with its main airport (LAX, MIA, LAS) is searched as the city, so results can include the city's other airports (ONT for LAX); `destination_type: "airport"` (and `origin_type` for the origin) limits the search to that airport. The OpenAPI description is at `https://api.gojinko.com/doc`.
- MCP: `https://mcp.builders.gojinko.com/mcp` with `Authorization: Bearer <key>`. Its tools include `flight_search` and `hotel_search`.
- The key is an ordinary server-to-server key. It keeps working when the agent's access token is renewed and after a person claims the organization.

## Handing the organization to a person (optional)

- auth.md step 3 describes the claim. On this environment its `verification_uri` opens `https://dashboard.gojinko.com/claim`; the person signs in there and reads back the code the page shows.
- The claim request carries the person's email as `login_hint`. A person who already belongs to a Jinko organization can't claim a second one, and the page says so.
- After the claim, the person is an admin of the organization. The agent keeps its admin role and its key, and the person can change the agent's role or remove it; removal revokes the agent's keys.
- An unclaimed organization is suspended when the registration's claim window ends (3 days on this environment).

## Limits

- Registrations: 5 per IP per hour, and 100 per environment per hour (WorkOS).
- Access tokens last about 5 minutes; auth.md step 4 issues a new one from the stored assertion.
- Claim links last about 5 minutes.
- Anonymous registrations carry no refresh token. Their identity assertion (`identity.expires_at`) lasts until the claim deadline (`claim.expires_at`, 3 days), so step 5 (refresh) applies only after a person claims the organization, when the claimed identity includes `identity.refresh_token`.
- WorkOS's edge refuses `POST https://auth.gojinko.com/agent/identity` requests that carry Python's default urllib User-Agent (`403 error code: 1010`); requests with an explicit User-Agent header, such as curl's, are accepted.