---
title: Getting started
description: Pick a Basalt developer surface, obtain the correct credential, and make a first bounded request.
slug: getting-started
path: /getting-started
section: Overview
availability: supported
nav_order: 2
canonical_url: https://developers.basaltnotes.com/getting-started
markdown_url: https://developers.basaltnotes.com/getting-started.md
mirror_url: https://basaltnotes.com/developers/getting-started
---
# Getting started

Basalt deliberately has more than one developer surface because the trust boundary for a one-time handoff is different from the trust boundary for an authenticated agent or a partner product.

## 1. Pick the contract

**Use Handoff** when the external product has produced a bounded work product and the next natural step is for the user to continue it in Basalt.

**Use MCP** when an agent client needs bounded tools over a Basalt Hosted mapping.

**Use the Developer REST API** when your backend or script needs direct hosted-vault reads, dry-run mutations, transactions, or provenance events.

**Use Automation/OpenAPI** for versioned events, approval-required action proposals, triggers, or webhook delivery workflows.

**Use Product Runtime** when you are building another product surface over Basalt's stable application DTOs and authorization model.

## 2. Obtain the right credential

| Surface | Credential |
|---|---|
| Handoff | Basalt-issued scoped Handoff client credential (`bhc_…`), kept server-side |
| Hosted MCP | Hosted access token (`bda_…`) from **AI Connections & API** settings; Premium and above |
| REST / Automation | The same hosted access-token format, independently authorized for Developer & Agent or Team |
| Product Runtime as a human developer | Entitled developer bearer token |
| Product Runtime as an installed product | Installation service-principal credential |
| First-party Basalt product | First-party cookie/session where explicitly supported |

A vault `mappingId`, `workspaceId`, `vaultId`, Handoff token, or Product Experience ID is **not** a credential by itself.

## 3. Keep hosted and local boundaries explicit

Hosted APIs work with Basalt Hosted state that the user has explicitly connected. They cannot read an arbitrary local browser vault.

When examples use `BASALT_ORIGIN`, set it to the supported Basalt application/API origin for the environment you are using. The Developer Center hostname is documentation infrastructure; do not assume it is the API origin unless the deployed reference explicitly says so.

## 4. Make a read before a write

For REST/MCP, start by listing or reading the target hosted mapping. For Product Runtime, read context/capabilities before attempting a mutation. For Handoff, create a temporary handoff and redirect the user; do not import on link-open.

## 5. Preview mutations

Basalt mutation surfaces are intentionally conservative:

- REST note writes and transactions default to dry run.
- MCP note mutations use the same hosted transaction boundary.
- Product Runtime hosted publishes use explicit preview/publish behavior and revision controls.
- Automation bridge actions are proposals until the applicable approval/execution boundary is satisfied.

## 6. Preserve idempotency and current revisions

Use stable idempotency keys for retryable write operations. When modifying or deleting an existing note, provide the current revision/hash required by that API. Basalt should reject stale writes rather than silently overwriting newer knowledge.

## 7. Treat returned provenance as part of the contract

Do not strip source identifiers, revisions, actor information, or knowledge fingerprints if your workflow depends on auditability. Provenance is part of Basalt's decision-intelligence model, not decorative metadata.