Create a Developer API application and key

Set up Developer API access from your coding agent using Sign in with Kismet. The OAuth-connected Developer MCP can create applications, configure TEST or LIVE installations and their grants, and issue credentials. You do not need to open the dashboard to copy a key. The dashboard remains an alternative for manual setup.

An application is the long-lived integration record. Each installation identifies its collection, environment, capability grants, and authorized browser origins. Credentials belong to an installation and cannot widen those grants.

Keep TEST and LIVE separate

Create separate installations and credentials for TEST and LIVE. TEST may read real published CMS content, but its bookings and telemetry remain sandboxed. A TEST action never becomes a production reservation or charge.

Rate limits and retries

GET and HEAD reads share one allowance across an installation’s credentials: a 600-request bucket that replenishes continuously at 10 requests per second (600 per minute sustained). Short bursts use the available balance. Creating or rotating keys does not increase that allowance. Writes, emails, and verification keep independent, stricter limits.

On HTTP 429, wait for Retry-After before retrying. The SDK exposes this delay as KismetApiError.retryAfterSeconds (also available on other failed responses that include the header). The SDK does not automatically retry. If no valid delay is provided, use bounded exponential backoff with jitter. Deduplicate concurrent reads and avoid refetching on every focus event; do not share private guest data between visitors. Treat throttling as temporary, not as an unavailable offer.

TEST supports realistic integration testing, not production operation. Staging approval, expiration, origin restrictions, and TEST/LIVE isolation still apply.

Prerequisites

• A Kismet account with effective ADMIN or DEVELOPER access to the target collection, or GLOBAL_OWNER authority.
• The collection slug and the name of the integration you are building.
• For server credentials, an authorized server-side secret store your client can write to securely. Kismet returns the server secret once; it does not configure your hosting provider’s secret store.

If an AI coding agent is doing the integration, install or connect the Kismet Developer plugin and MCP first. Claude and Codex can install the complete plugin; Lovable connects to the same public MCP through a custom Chat connector.

Set up through your coding agent

1. Connect https://mcp.kismet.travel/developer-mcp using OAuth, then complete Sign in with Kismet. Do not select API-key authentication for this setup: a key cannot create another key.
2. Refresh the tool list after sign-in. Your connection should expose list_developer_applications, create_developer_installation, and issue_developer_credential when your collection role permits them.
3. Ask the agent to inspect existing applications and installations, preview only the access needed by your application, and show you the collection, environment, grants, origins, and credential type before confirming.
4. Have it issue the credential and save the once-only server secret directly to the approved server secret destination. Do not paste it into a prompt or client-side environment variable.
5. Verify the returned installation with get_developer_installation, then run a permitted SDK/API request from your server. Saving a credential is not proof that the integration works.

For example, in Lovable, Claude, or Codex:

Use Kismet Developer to set up TEST access for my application on your-collection. Inspect existing applications first. Preview an installation with search.read and no browser origins. Ask me to approve the exact access. Before issuing a SERVER_SECRET, confirm which server-side secret store you can securely write to. Save the result there as KISMET_DEVELOPER_API_KEY, without displaying it in chat. Then verify a search request from the server.

The tool sequence is:

Step	MCP tool	Input and result
Inspect	list_developer_applications	collection_slug; reuse an appropriate application when present.
Create, if needed	create_developer_application	collection_slug, name, slug; omit confirm for preview, then use confirm: true after approval.
Activate, if needed	activate_developer_application	The returned application_id; preview and confirm.
Grant access	create_developer_installation	collection_slug, application_id, explicit environment, grants, and origins; preview and confirm.
Issue	issue_developer_credential	Returned installation_id, kind: "SERVER_SECRET", optional expires_at; preview and confirm.
Verify	get_developer_installation	Check the returned ID, environment, grants, and credential metadata.

For example, the installation preview input for server-side search is:

{
  "collection_slug": "your-collection",
  "application_id": "<returned-application-id>",
  "environment": "TEST",
  "grants": [{ "capability": "search.read" }],
  "origins": [],
  "confirm": false
}

Use the actual returned application ID. After approval, repeat the same input with confirm: true. Do not add unrelated capabilities. For events and webhooks, use the event access grants and setup prompt.

OAuth authorizes the agent to manage access; your deployed server uses the issued installation credential. It must not reuse your personal OAuth token. The MCP does not edit grants or environment in place: create a separate installation when those requirements differ.

Secret storage depends on your client

Kismet’s issuance tool returns the secret to the connected client. It does not provide a built-in Lovable or hosting-provider secret-store integration. Establish that secure destination before issuance. If the client cannot persist the result securely, stop at the installation preview and resolve that integration; do not expose the secret in chat as a workaround.

If management tools are missing, check that this is the Developer MCP, not the guest MCP, and that the connection completed OAuth with developer:mcp. Refresh discovery after signing in. Confirm your role on the target collection; a role on a different collection does not grant access here. No Developer mode dashboard toggle is needed for MCP setup.

Sign in from a remote machine or an agent session

The sign-in waits for a browser callback on the machine that started it. Two setups need an extra step:

• Run the sign-in yourself, not inside the agent’s own command. An agent that runs the login as one of its tool calls cannot receive the callback, and the login is cancelled. Run it in a terminal you control: codex mcp login --scopes developer:mcp kismet-developer for Codex, or /mcp in Claude Code.
• On a remote or headless machine (SSH session, server, NAS), add --no-browser. Open the printed link on any device and approve. The browser then lands on http://127.0.0.1:<port>/callback/..., which does not load there; that is expected. Copy the full URL from the address bar and paste it at the prompt within a few minutes, before the code expires.

A running agent session keeps the tools it loaded at start. After signing in, restart the session or refresh its tools (/mcp) so the management tools appear.

Dashboard alternative

The following steps manage the same applications, installations, and credentials manually.

1. Open the Developer API settings

1. Open the account menu and turn on Developer mode.
2. Open Collections, choose the collection, and select Settings.
3. Select the Developer API tab.

Developer mode changes the interface and activates TEST-mode views; it does not turn an existing LIVE credential into a TEST credential. Environment is fixed on each installation.

To preview unpublished catalog groups and rooms, you also need explicit, expiring manager approvals. A TEST key or Developer mode alone does not expose unpublished content. Follow Staging catalog previews for the separate setup and supported reads.

2. Create and activate an application

Enter a name, stable lowercase slug, and optional description. Create the application, then activate it. Applications begin private and cannot receive an installation until they are active.

Use one application for one deployed integration. Create separate applications when different sites or partners need independent revocation, grants, or audit history.

3. Create an installation

Choose TEST for development and select only the capabilities the application needs. The useful minimum for natural-language discovery is:

• search.read to call the collection-scoped search operation.

Most search result pages also need:

• vacation_rentals.read for cards and detail reads;
• media.read and amenities.read for presentation data;
• rates.read for indicative calendar-backed display pricing;
• reviews.read and policies.read when those sections are rendered;
• collections.read for manager-level content.

Add exact browser origins only when issuing a publishable credential. Origins do not apply as wildcards: http://127.0.0.1:3000 and http://localhost:3000 are different origins.

4. Issue a credential

Use a restricted server credential for Next.js Server Components, route handlers, BFF routes, and the first natural-language search smoke. Use a publishable credential only for explicitly browser-safe reads from an authorized origin.

Server secrets are shown once. Save the value in your server secret manager or local .env.local file when it is issued; it cannot be recovered later. Keep it out of browser code, source control, logs, and agent prompts.

Publishable keys remain visible and copyable in the credential inventory. They are intended for browser-safe reads from the installation’s exact authorized origins. They do not replace a server secret for guest operations or writes.

KISMET_API_BASE_URL=https://api.ksmt.app/v1
KISMET_DEVELOPER_API_KEY=your_one_time_server_key

Never use a NEXT_PUBLIC_ variable for a server credential. To inspect an installation or use authorized telemetry tools through the Developer MCP, configure the key in the MCP client’s secure credential storage—not in a tool argument or prompt. See MCP authentication and access.

The key already carries its collection: GET /developer/credential returns the collection, environment, and capability grants the presenting key resolves, and the SDK reads it once for you. You never need to configure a collection slug; pass one only to override.

Smoke natural-language search

Install an SDK build that includes bookableProduct.search, then run this from a server-only module:

import { createKismetClient } from '@kismet-tech/sdk/server';

const client = createKismetClient({
  apiKey: process.env.KISMET_DEVELOPER_API_KEY!,
  baseUrl: process.env.KISMET_API_BASE_URL!,
});

const result = await client.bookableProduct.search({
  query: 'a quiet family stay near the water with a pool',
  topK: 12,
});

console.log(result.ranked);

You can verify the credential and API independently of the SDK. First read the key’s own collection — the slug in the response is what the collection-scoped routes use:

curl "$KISMET_API_BASE_URL/developer/credential" \
  --header "Authorization: Bearer $KISMET_DEVELOPER_API_KEY" \
  --header 'Accept: application/json'
# Copy the collection "slug" from the response:
export COLLECTION_SLUG=your-collection-slug

Then search within that collection’s slug:

curl --request POST \
  "$KISMET_API_BASE_URL/developer/collections/$COLLECTION_SLUG/search" \
  --header "Authorization: Bearer $KISMET_DEVELOPER_API_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"query":"a quiet family stay near the water with a pool","topK":12}'

The response should report meta.source: "developer-api". Treat ranked[] as discovery candidates, not availability, a quote, or a booking offer. Use the availability APIs for availability and the configured managed checkout for an authoritative offer.

Common failures

Response	What to check
401	The credential is complete, active, unexpired, and sent as Authorization: Bearer ….
403	The installation has search.read, the collection is within its grants, and a publishable request has an exact authorized origin.
Empty ranking	The collection has published BookableProducts in the current search corpus; unpublished CMS records are intentionally excluded.
Deterministic fallback	The transport works, but the target environment lacks or has not populated its semantic-search corpus. Do not count fallback output as semantic-ranking evidence.

Inspect, rotate, and revoke credentials

Open the installation to inspect credential status, creation and expiry information, and last-used time when present. Last-used time helps identify active integrations; it is not a detailed per-request usage report.

Rotation is a manual replacement workflow:

1. Issue a replacement credential for the intended installation and store it securely.
2. Update the integration to use the replacement and verify a permitted request succeeds.
3. Revoke the previous credential with a reason after confirming the integration has switched.

There is no automatic rotation or atomic overlap workflow. For immediate revocation, locate the credential by its ID or displayed prefix and revoke it. A lost server secret cannot be recovered; issue a replacement. A suspected server-secret exposure is a reason to revoke promptly, not to wait for scheduled rotation.

You can also manage this lifecycle through the Developer MCP access tools after signing in with an authorized Kismet account. API keys cannot issue other API keys.

For access or integration help, contact [email protected].

Machine-readable sources

• This guide as Markdown
• llms.txt
• Natural-language search reference
• Developer API OpenAPI