---
title: "Quickstart"
description: "Vom Sandbox-Schlüssel zum ersten Kontakt in vier Schritten: Schlüssel anlegen, wer bin ich, Kontakt anlegen, in Bodo nachsehen."
lang: de
url: https://developers.bodo-app.com/quickstart/
apiVersion: 2026-11-01
---

# Quickstart

Vom Sandbox-Schlüssel zum ersten Kontakt in vier Schritten: Schlüssel anlegen, wer bin ich, Kontakt anlegen, in Bodo nachsehen.

## Sandbox-Schlüssel anlegen

In Bodo: Einstellungen › Schnittstellen › API-Schlüssel › „Schlüssel anlegen“.

| Schritt im Assistenten | Wert für den Quickstart |
| --- | --- |
| Umgebung | `test`, bindet an „Musterfirma GmbH (Sandbox)“ |
| Scope | Kontakte: Lesen & Schreiben · Firmen: Lesen · Rest: Kein Zugriff |
| IP-Bindung | deine aktuelle IP, etwa `198.51.100.7/32` (Pflicht für Schreiben) |
| Ablauf | 30 Tage (Vorgabe) |

> **In der Sandbox ist die API schon an** Die Sandbox deiner Organisation hat `apiAccess` bereits auf an, nur mit Testdaten. Für den Quickstart brauchst du deshalb keine Freigabe eines Admins. Einzige Voraussetzung: Deine Organisation hat in Bodo erklärt, ob für sie ein Berufsgeheimnis gilt; ohne diese Erklärung bleibt die API auch in der Sandbox aus. Für einen Live-Schlüssel (`live`) muss ein Org-Admin die API deiner Organisation erst unter Einstellungen › Schnittstellen › API freigeben; bis dahin fehlt dort der Knopf.

Das Geheimnis wird nur einmal angezeigt. Leg es als Umgebungsvariable ab:

**Shell**

```bash
export BODO_API_KEY="bodo_uk_test_…"
```

## Wer bin ich?

`GET /v1/me` nennt Prinzipal, Organisation und den eigenen Schlüssel mit Ablauf, Pin und wirksamen Scopes.

**Anfrage**

```bash
curl https://api.bodo-app.com/v1/me \
  -H "Authorization: Bearer $BODO_API_KEY"
```

**Antwort**

```http
HTTP/1.1 200 OK
Bodo-Version: 2026-11-01
Request-Id: req_01JB6…

{
  "authMethod": "apiKey",
  "principalType": "user",
  "principalId": "usr_…",
  "principalName": "Max Mustermann",
  "organization": {
    "id": "org_…",
    "name": "Musterfirma GmbH (Sandbox)"
  },
  "key": {
    "kidShort": "…Kx9a",
    "environment": "test",
    "versionPin": "2026-11-01",
    "expiresAt": "2026-12-03T09:00:00Z"
  },
  "grant": null,
  "scopes": [
    "contacts:read",
    "contacts:write",
    "companies:read"
  ],
  "openFamilies": [],
  "apiVersion": "2026-11-01"
}
```

## Kontakt anlegen

Schreiben startet im Preview-Kanal und braucht deshalb `Bodo-Preview: true`. Mit der ersten Folgeversion steigt Schreiben für `contacts`, `companies` und `tasks` auf stable auf, dann entfällt der Header. Der `Idempotency-Key` ist bei POST Pflicht; mit demselben Key ist eine Wiederholung gefahrlos.

**curl**

```bash
curl -X POST https://api.bodo-app.com/v1/contacts \
  -H "Authorization: Bearer $BODO_API_KEY" \
  -H "Bodo-Preview: true" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Erika","lastName":"Mustermann","email":"erika@musterfirma.de"}'
```

Oder mit dem [SDK](/sdks/), das Preview-Header und Idempotency-Key selbst setzt:

**Kontakt anlegen mit dem SDK**

TypeScript · SDK:

```typescript
// Portal D2 · Quickstart — steps 2 and 3 with the SDK: who am I, then one contact.
// Run: BODO_API_KEY=bodo_uk_test_… bun examples/quickstart.ts
import { Bodo, BodoApiError } from "@bodo/api";

const bodo = new Bodo({
  apiKey: process.env.BODO_API_KEY,
  preview: true, // writes are in the preview channel: sends Bodo-Preview: true
});

// Step 2 · Who am I?
const me = await bodo.me();
console.log(me.principalType, me.authMethod);

// Step 3 · Create a contact. The SDK sets the Idempotency-Key itself, retries included.
try {
  const contact = await bodo.contacts.create({
    firstName: "Erika",
    lastName: "Mustermann",
    email: "erika@musterfirma.de",
  });
  console.log(contact.id, contact.displayName);
} catch (err) {
  if (err instanceof BodoApiError) {
    console.error(err.code, err.requestId); // the stable code, never the text
  }
  throw err;
}
```

Python · SDK:

```python
# Steps 2 and 3 with the SDK: who am I, then one contact.
# Run: BODO_API_KEY=bodo_uk_test_… python examples/quickstart.py
import os

from bodo_api import Bodo, BodoApiError

bodo = Bodo(
    api_key=os.environ["BODO_API_KEY"],
    preview=True,  # writes are in the preview channel: sends Bodo-Preview: true
)

# Step 2 · Who am I?
me = bodo.me()
print(me.principal_type, me.auth_method)

# Step 3 · Create a contact. The SDK sets the Idempotency-Key itself, retries included.
try:
    contact = bodo.contacts.create(
        first_name="Erika",
        last_name="Mustermann",
        email="erika@musterfirma.de",
    )
    print(contact.id, contact.display_name)
except BodoApiError as err:
    print(err.code, err.request_id)  # the stable code, never the text
    raise
```

201 Created · `Location: /v1/contacts/con_…` · `ETag`

## In Bodo nachsehen

Der Kontakt steht in der Sandbox. Die Chronik trägt die Stecker-Marke, die Herkunft ist also sichtbar.

**Max Mustermann** hat den Kontakt Erika Mustermann angelegt, über die API.

[Weiter zur Referenz](/reference/)