# Connect onOffice: API user, rights, token

<Lead>
Set up the onOffice integration once, centrally. After that every tool that
needs onOffice uses the same connection automatically. No tool asks for its own
credentials.
</Lead>

Manage the connection under **Settings → Integrations → onOffice**.

## 1. Create an API user in onOffice

<Steps>
<Step title="Open user management">
In onOffice: **Extras → Settings → Users**.
</Step>
<Step title="Create the API user">
Create a new user and mark it as an **API user** (e.g. username `reosa-api`).
</Step>
</Steps>

## 2. Generate token and secret

Generate a **token** and a **secret** for the API user.

<Warning title="The secret is shown only once">
onOffice shows the secret exactly once. Copy it immediately and keep it safe. If
it is lost, generate a new one.
</Warning>

## 3. Grant the rights

For every sync to work, the API user needs at least:

<Checklist>
<ChecklistItem>Read addresses (all) and write (all).</ChecklistItem>
<ChecklistItem>Read objects (all) and write (all).</ChecklistItem>
<ChecklistItem>**Disable** the checkbox "can only read objects published on the website".</ChecklistItem>
<ChecklistItem>Read and write agent log / activities (all).</ChecklistItem>
<ChecklistItem>Enable "read user data via API" (for user selection lists).</ChecklistItem>
</Checklist>

<Info title="Why 'only published objects' must be off">
If that checkbox stays active, onOffice returns only some of your objects and the
object sync stays incomplete. Disable it for a complete import.
</Info>

## 4. Connect in the platform

<Steps>
<Step title="Open the integration">
Go to **Settings → Integrations → onOffice**.
</Step>
<Step title="Enter the credentials">
Leave the **API URL** as is (default:
`https://api.onoffice.de/api/stable/api.php`). Enter **token** and **secret**.
</Step>
<Step title="Connect and test">
Click **"Connect & test"**. On success the page shows **"Connected"**.
</Step>
</Steps>

<Success title="Stored securely">
Your credentials are encrypted server-side and never shown again. You can verify
or disconnect at any time. After saving, the token and secret fields are locked;
use "Replace" to store new ones when needed.
</Success>

## 5. Control the data flow

After connecting, two switches let you decide what flows:

<DefinitionList>
<DefItem term="Fetch addresses from onOffice">The platform reads contacts and objects from onOffice. Nothing is changed in onOffice.</DefItem>
<DefItem term="Write changes back to onOffice">The platform writes updates directly into your onOffice. Only enable this if the platform may write into your CRM.</DefItem>
</DefinitionList>

Both switches ask for confirmation before any change, so nothing flips by accident.

## 6. Map team members

Below the connection you find the list of your members, each with a field for
the onOffice user. The platform suggests a mapping by email address; you can
change or clear it at any time.

The mapping has three effects:

<DefinitionList>
<DefItem term="Tasks">A member only sees the tasks that run on their onOffice user.</DefItem>
<DefItem term="Assignment">When DB-Leads assigns a contact, the platform writes this username into the configured onOffice field.</DefItem>
<DefItem term="Agents log">Notes, call outcomes, the reasoning behind a readiness rating and entries made through the assistant appear in the agents log under this user, not under the API user. Entries a scan creates on its own stay with the API user.</DefItem>
</DefinitionList>

<Info title="Nothing is guessed without a mapping">
If a member has no onOffice user mapped, onOffice records the API user for
their entries and the assignment stays untouched. A wrong colleague in the
agents log would be worse than none.
</Info>

## Next

<CardGrid>
<Card href="/help/integrations/onoffice/adressen" title="Address sync" eyebrow="Next step">
Import your address book into the central platform address book.
</Card>
<Card href="/help/integrations/onoffice/objekte" title="Object sync" eyebrow="Next step">
Import your properties with the correct status.
</Card>
</CardGrid>