# Create a Developer API application and key

> Create collection-scoped TEST or LIVE installations and credentials from your Kismet account.


Authorized collection administrators and developers can manage Developer API access from the collection's Kismet settings. An application is the long-lived integration record. Each installation fixes 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.

## Prerequisites

- Sign in to [Kismet](https://kismet.travel/account).
- Open the collection you are integrating.
- Your effective collection role must be `ADMIN`, `DEVELOPER`, or `GLOBAL_OWNER`. An administrator has the same Developer API rights as a developer for that collection.

If an AI coding agent is doing the integration, install or connect the
[Kismet Developer plugin and MCP](https://developers.kismet.travel/mcp.md) first. Claude and Codex can install
the complete plugin; Lovable connects to the same public MCP through a custom
Chat connector.

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

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

The complete token is shown once. Copy it immediately into a secret manager or local `.env.local` file. Kismet stores a one-way credential representation and cannot recover the token later. Revoke a credential immediately if it is exposed; issue a replacement rather than trying to edit it.

```dotenv
KISMET_API_BASE_URL=https://api.ksmt.app/v1
KISMET_DEVELOPER_API_KEY=your_one_time_server_key
KISMET_COLLECTION=juniper-holiday-home
```

Never use a `NEXT_PUBLIC_` variable for a server credential, commit it, paste it into an agent prompt, or send it to the Developer MCP.

## 5. Smoke natural-language search

Install an SDK build that includes Developer API v0.7.2 search, then run this from a server-only module:

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

const client = createKismetClient({
  apiKey: process.env.KISMET_DEVELOPER_API_KEY!,
  collection: process.env.KISMET_COLLECTION!,
  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:

```sh
curl --request POST \
  "$KISMET_API_BASE_URL/developer/collections/$KISMET_COLLECTION/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 and quote surfaces for those decisions.

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

## Revoke access

Open the installation, locate the safe credential inventory entry by its displayed prefix, and revoke it with a reason. Revocation is immediate. The full secret is never displayed again.

## Machine-readable sources

- [This guide as Markdown](/guides/developer-access.md)
- [`llms.txt`](/llms.txt)
- [Natural-language search reference](https://developers.kismet.travel/api/reference/search-bookable-products.md)
- [Developer API OpenAPI v0.7.2](/openapi.json)