> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hocdoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Settings

> Workspace, brand, sender and account: what you can set and who may do it.

Settings have nine tabs: **Workspace**, **Brand**, **Sender**, **Domain**, **Follow-ups**, **Integrations**, **Account**, **Approvals** and **Audit log**. You reach them via "Settings" in the navigation.

## Who can do what

| Tab | View | Change |
| - | - | - |
| Workspace | all roles | Owner and Admin |
| Brand | all roles | Owner and Admin |
| Sender (with "Accept button" and "After acceptance") | all roles | Owner and Admin |
| Domain | all roles | Owner and Admin |
| Follow-ups | all roles | Owner and Admin |
| Integrations: "Connections" card | all roles | Owner and Admin (in preparation) |
| Integrations: "Notifications" card | Owner and Admin | Owner and Admin |
| Integrations: "API keys" card | Owner and Admin | Owner and Admin |
| Integrations: "Webhooks" and "Delivery log" cards | Owner and Admin | Owner and Admin |
| Integrations: "Public API" card | all roles | nothing to change |
| Account | each person for their own account | each person for their own account |
| Approvals | all roles | Owner and Admin (Team plan) |
| Audit log | Owner and Admin (Team plan) | nothing to change |

Members and viewers see the note "Read only. Only admins and owners can change these settings." in all tabs except "Account": Workspace, Brand, Sender, Domain, Follow-ups and Integrations. In the first three tabs the fields are then locked and there is no Save button. In the "Integrations" tab the cards "Notifications", "API keys", "Webhooks" and "Delivery log" are missing for them. More about roles is under [Team and roles](https://docs.hocdoc.com/en/guides/team-and-roles.md).

## Workspace

Here you maintain your workspace's name, slug, time zone and currency. Below are two cards: "Accepted out of 10 offers before HocDoc" and "Language of new offers". With **Save** you apply the changes.

| Field | Rule |
| - | - |
| "Name" | 2 to 80 characters. It appears, for example, in the subject and text of the invitation email. |
| "Slug" | 2 to 48 characters: lowercase letters, digits and single hyphens. It must be unique in the app, otherwise "This slug is already taken. Please choose another one." appears. |
| "Time zone" | Selection from a fixed list. New workspaces start with Europe/Berlin. |
| "Currency" | Selection from 24 currencies (EUR, CHF, USD, GBP and more). New workspaces start with EUR. |

### What the time zone does

The time zone determines "the days in charts and key figures as well as the dates and deadlines shown". This affects, for example, the overview, the analytics and your offers' deadlines. Emails also state dates in the workspace's time zone. The public offer page shows deadlines in the sending workspace's time zone, so they read the same for sender and recipient.

### What the currency does

The workspace's currency is the default for the price when you create a new service in the [Library](https://docs.hocdoc.com/en/guides/library.md). You can change it there per entry. Nothing is converted.

### Accepted out of 10 offers before HocDoc

The card "Accepted out of 10 offers before HocDoc" asks: "Optional: How many out of 10 offers were accepted at your company before you started using HocDoc?" In the "Accepted out of 10 offers" field you choose a number from 0 to 10 or "Not stated". With **Apply** you save. The card names the date of the entry ("Entered on …").

Owners and admins change the figure. All other roles see the value locked. HocDoc uses the figure as a comparison value on the Analytics page: the card "Comparison with the figure before HocDoc" sets it against the actual close rate (see [Analytics](https://docs.hocdoc.com/en/guides/analytics.md#comparison-with-the-figure-before-hocdoc)).

## Brand

Brand applies to the public offer page your recipients see and to the canvas and preview in the builder, not to the rest of the app. Next to the form you see a "Preview" with your settings.

### Logo

With **Upload logo** you choose a file, with **Replace logo** you swap it, with **Remove logo** you take the logo away again. It is only saved with **Save**.

* PNG, JPEG and WebP are allowed, up to 2 MB.
* Landscape format with an aspect ratio between 1:1 and 5:1 works best.
* The logo appears in the header of the offer page. Without a logo, the header shows the HocDoc logo and, except on narrow screens, the workspace's name.

If the logo is very wide (wider than 6:1) or very tall (narrower than 1:2), the form warns you that it will become flat or narrow and hard to read in the header. You can still save it.

### Primary color

You choose the color with the "Color picker", via the "Color suggestions" or as a "Hex value" with six characters, for example 0247EF. With **Use default** you return to the default color. Without input, the default color stays active.

### Font

You choose one of five fonts: Geist (default), Inter, DM Sans, Source Serif 4 or Playfair Display.

> [!NOTE]
>
> Logo, color and font always apply in their current state. Changes therefore also affect offers you have already sent. The offer PDF shows neither logo nor primary color.

## Sender

The "Sender" tab determines what appears in emails to recipients and in the footer of the public offer page. The "Preview" next to the form shows how "From" and "Reply to" look in the email and what the footer will be. Without entries no footer appears.

| Field | Effect |
| - | - |
| "Sender name" | Appears as the name in the email's sender. The address stays unchanged. Without an entry, the workspace's name appears there. At most 120 characters. |
| "Reply-to address" | Recipients' replies go to this address. |
| "Company name" | Line in the footer. At most 120 characters. |
| "Website" | Link in the footer. |
| "Contact email" | Line in the footer. |
| "Phone" | Line in the footer. At most 40 characters. |
| "Address" | Multi-line, at most 500 characters. Lines in the footer. |
| "Link to the legal notice" | Link in the footer. "https only. Recorded with the offer when it is accepted." |
| "Link to the terms and conditions" | Link in the footer. "https only. Recorded with the offer when it is accepted." |

All fields are optional. Links must begin with `https://`. The footer appears in the emails to recipients and on the public offer page.

> [!NOTE]
>
> The sender details are recorded on the offer when sending. Changes therefore apply to offers you send afterwards. Offers already sent keep the state from the send.

### Accept button card

Below the sender form, before the "After acceptance" card, is the "Accept button" card with its own Save. It sets the text of the button with which the recipient completes the acceptance. It applies to every new send. Sent offers keep their state.

| Field | Rule |
| - | - |
| "Accept button text" | At most 40 characters, one line. Empty: default text. The button shows the word "Accept" and the offer title in quotation marks. With several signers, the button without your own text is called "Sign". |

* Whitespace at the edges is removed.
* Double curly braces are not allowed, and placeholders are not resolved here. The message reads: "The accept button text can't contain double curly braces."
* Line breaks, control characters, invisible characters and a text without any visible character are not allowed. The message reads: "The accept button text contains characters that aren't allowed."
* The field accepts at most 40 characters, and more cannot be entered.
* If saving fails, it says: "The accept button text couldn't be saved."
* Owners and admins can change and save. Members and viewers see the field locked and without a Save button.

Where the text appears on the recipient's page is described in [Acceptance and certificate](https://docs.hocdoc.com/en/guides/acceptance-and-certificate.md#text-of-the-accept-button).

### After acceptance card

Below the sender form is a card of its own with its own Save. It sets the default for the step that follows acceptance, for example a link to book an appointment.

| Field | Rule |
| - | - |
| "Link after acceptance" | https only. Appears after acceptance as a button and in the confirmation email. |
| "Button text" | At most 60 characters, no double curly braces. Without your own text, the button says "Schedule a meeting". |

* Without a link no button appears. A text alone is not saved, and the field points this out.
* The card is a default for new offers. In the send dialog you can change link and text per offer.
* Sent offers keep their state.
* The button only appears after acceptance and opens the link in a new tab.

More about the flow is under [Acceptance and certificate](https://docs.hocdoc.com/en/guides/acceptance-and-certificate.md) and [Sending](https://docs.hocdoc.com/en/guides/sending.md).

### Onboarding form after acceptance card

Below the "After acceptance" card is the "Onboarding form after acceptance" card. It collects questions the recipient answers after acceptance. Owners and admins can manage it.

* **Add question** creates a question. The question text has at most 200 characters and sits on one line. There are at most 10 questions ("At most 10 questions.").
* **Move up** and **Move down** sort the questions. **Remove question** deletes a question.
* Under **Answer type** you choose "Short text", "Long text" or "File upload". For a file question, the field **Note for the recipient (optional)** is added. More under [Files after acceptance](https://docs.hocdoc.com/en/guides/file-upload-after-acceptance.md).
* **Required** makes the answer mandatory.
* Under "Suggestions to add" are "Billing address", "Contact person for the project" and "Preferred start date". An added suggestion is a question like any other.
* Without questions there is no form ("No questions yet. Without questions there is no form.").

The card is a default. When sending, you choose per offer whether the form appears. Sent offers keep their state: later changes to the questions only apply to offers you send afterwards. What the recipient sees is described under [Acceptance and certificate](https://docs.hocdoc.com/en/guides/acceptance-and-certificate.md).

## Domain

In the "Domain" tab you enter a custom domain, a subdomain such as `angebote.deine-firma.de` or the root domain, so that offer links sit under your address instead of `app.hocdoc.com`. The "Custom domain" card shows domain, status, the DNS records, **Check again** and **Remove**. Members and viewers see domain and status without buttons. The full guide is under [Custom domain](https://docs.hocdoc.com/en/guides/custom-domain.md). A second card, "Sender domain for emails", makes sure emails to recipients and signers come from an address on your domain. It is in the same section of the guide: [Sender domain for emails](https://docs.hocdoc.com/en/guides/custom-domain.md#sender-domain-for-emails).

If the root domain has a www variant, you choose it on the "Custom domain" card, and the DNS list names the TXT record for proof of ownership. Both are in the guide: [www variant](https://docs.hocdoc.com/en/guides/custom-domain.md#www-variant-of-the-root-domain) and [Proof of ownership](https://docs.hocdoc.com/en/guides/custom-domain.md#proof-of-ownership).

## Follow-ups

In the "Follow-ups" tab you switch on automatic follow-ups. The card is called "Follow up automatically". You switch on each of the four rules ("Not opened", "Opened but not accepted", "Expiring soon", "Signature pending") individually and set the days (a whole number from 1 to 30). Without a setting, everything is off. The guide is under [Automatic follow-ups](https://docs.hocdoc.com/en/guides/automatic-follow-ups.md).

## Integrations

In the "Integrations" tab you set up notifications to Slack and Microsoft Teams and create API keys and webhooks. With a key, your own systems read this workspace's offers and their timeline. With a webhook, HocDoc tells your system when something happens to an offer. The tab has six cards: **Connections**, **Notifications**, **API keys**, **Webhooks**, **Delivery log** and **Public API**. The **Notifications** and **Connections** cards are described in the guide [Notifications and connections](https://docs.hocdoc.com/en/guides/notifications.md). Webhooks have a section of their own under [Webhooks](#webhooks). The description of the interface itself is in the [API documentation](https://docs.hocdoc.com/en/api/introduction.md), authentication under [Authentication](https://docs.hocdoc.com/en/api/authentication.md).

### Who can do it

Owners and admins see the "API keys" card and manage the keys. Members and viewers see the note "Read only.", the "Connections" card (with the note "Admins and owners can connect and disconnect.") and the "Public API" card, but no keys. If the list cannot be loaded, it says "Loading failed." with "API keys couldn't be loaded. Please reload the page." If you lack the right when creating or revoking, for example after a role change with the page open, it says: "Only admins and owners can manage API keys."

### What a key can do

"Access for your own systems." The dialog says: "The key reads the offers of this workspace. With write permission it can also create offers from templates, send and withdraw them." When creating, you choose the **Permission**: **Read only** or **Read and write**. With write permission, the key acts in your name: offers count as yours, and your role and the approval rules apply. More in the [API introduction](https://docs.hocdoc.com/en/api/introduction.md#writing).

### Create a key

**1. Open the dialog**

In the "API keys" card, choose **Create API key**. The dialog is called "Create API key".

**2. Name and expiry date**

**Name** is required (at most 80 characters, no control characters). It should say what the key is for, for example the name of the system. Under **Valid until (optional)** you choose a date. Without a date, the key is valid until it is revoked. Choose **Create**.

**3. Copy the key**

The "API key created" dialog shows the whole key in the **API key** field. With **Copy** you put it on the clipboard. The dialog says: "This key is only shown now. Keep it in a safe place." It only closes with **Done**, and a click next to it does not close it. Afterwards the key can no longer be displayed.

### Expiry date

* The date is optional.
* The key is valid until the end of the chosen day in the workspace's time zone.
* Selectable is today at the earliest and a date just under ten years ahead at the latest. Otherwise it says: "The expiry date must be in the future, at most 10 years ahead."
* Name and expiry date cannot be changed after creating. If you need other values, you revoke the key and create a new one.

### List

The list shows each key with its name and a status: **Active**, **Expired** or **Revoked**. Below are:

* the first 20 characters of the key, followed by an ellipsis. The app never shows the rest again.
* "Created on" with the date and "by" with the name of the person who created it,
* "Last used on" with date and time or "Not used yet",
* with an expiry date set, "Valid until" with the date, after expiry "Expired on",
* for a revoked key "Revoked on" with the date.

Times are in the workspace's time zone.

### Limit

A workspace has at most 10 keys that are not revoked. Expired keys count until you revoke them. The card's description names the state ("3 of 10 in use."). Once the limit is reached, **Create API key** is locked, and the card says: "The limit has been reached. Revoke a key to create a new one." There is also a limit for new keys: if too many are created in 24 hours, it says: "Too many API keys were created in the last 24 hours. Please try again later."

### Revoke a key

On a key, choose **Revoke** and confirm in the "API key revoked" dialog. The dialog says: "The key "\[Name]" stops working immediately. This cannot be undone." Afterwards it says "API key "\[Name]" revoked." The key stays in the list with the status "Revoked". The list shows all keys that are not revoked, plus the ten most recently revoked.

### Automatic revocation

A key ends with the admin role of the person who created it. If this person is removed from the workspace or is afterwards neither admin nor owner, all their keys are revoked. The list names the reason:

* "Revoked automatically on" followed by a date: "The person who created the key was no longer in this workspace from then on."
* "Revoked automatically on" followed by a date: "The person who created the key was no longer an admin from then on."

The Team page points this out. More under [Team and roles](https://docs.hocdoc.com/en/guides/team-and-roles.md).

### Webhooks

With a webhook, HocDoc calls an address of your system as soon as something happens to an offer. You do not have to poll. The "Webhooks" card says: "Send events to your own systems." Its description names the state ("2 of 5 endpoints added."). As long as there is no endpoint, it says: "No endpoint yet".

Only owners and admins see and manage webhooks. If you lack the right, for example after a role change with the page open, it says: "Only admins and owners can manage webhooks." If the card cannot be loaded, it says "Loading failed." with "Webhooks could not be loaded. Please reload the page."

The technical side is in the [API documentation on webhooks](https://docs.hocdoc.com/en/api/webhooks.md): structure of the calls, verifying the signature, retries and limits.

#### Add an endpoint

**1. Open the dialog**

In the "Webhooks" card, choose **Add endpoint**. The dialog says: "Every selected event is sent to this address as a signed call."

**2. Address and events**

Under **URL**, enter your system's address. Only https applies, for example [https://example.com/webhooks](https://example.com/webhooks). Under **Description (optional)** you say what the endpoint is for, for example the name of the system. Under **Events** you choose what the endpoint should receive. It only receives what is chosen there. Choose **Add**.

**3. Copy the secret**

The "Endpoint added" dialog shows the secret in the **Secret** field. With **Copy** you put it on the clipboard. The dialog says: "This secret is only shown now. Keep it safe." Your system uses it to check that a call really comes from HocDoc. Close the dialog with **Done**.

The events you can choose:

| Choice | When |
| - | - |
| "Offer sent" | An offer is sent, also as a new version. |
| "Opened for the first time" | The offer page of a sent version is opened for the first time. |
| "Signature added" | A person signs an offer with several signers. |
| "Offer accepted" | The recipient accepts the offer, or the last signature is added. |
| "Offer withdrawn" | You withdraw a sent offer. |
| "Offer expired" | The deadline of a sent offer has passed. The event arrives up to about 20 minutes after the deadline. |
| "Domain status changed" | The status of a domain for offer pages or of a sender domain has changed. Content: [Webhooks](https://docs.hocdoc.com/en/api/webhooks.md#body-of-domainupdated). |

A new endpoint starts with all events of this list selected. "Domain status changed" is not preselected, and you choose it yourself.

Rules for the address:

* Only https, without credentials and without @. Only the standard port 443 is allowed.
* The address needs a public name, for example example.com. An IP address is not allowed.
* Addresses on hocdoc.com, vercel.app and supabase.co are not allowed, nor is your workspace's own domain for offer pages. Then it says: "This address is not allowed."
* HocDoc does not follow redirects. If your system answers with a redirect, it counts as failed.

Two upper limits apply. A workspace has at most 5 endpoints. Once the limit is reached, **Add endpoint** is locked, and the card says: "The limit is reached. Delete an endpoint to add a new one." In addition, an account creates endpoints or channels for notifications in at most 20 workspaces (the workspaces in which the account has created endpoints or channels are counted). Once that is reached, it says: "You have already created webhooks in 20 workspaces. First delete the endpoints in a workspace where you no longer need them."

#### List

The list shows each endpoint with its address and a status: **Active**, **Paused** or **Paused automatically**. Below are "Last success on" with date and time or "Nothing delivered yet", for a failure "Last failure on" and "Added on" with the date and the person who added it. Times are in the workspace's time zone.

#### Send a test

With **Send test**, HocDoc sends a test event ("Test") to the endpoint. This way you check the address and the signature verification without needing an offer. Afterwards it says "Test sent. The result is in the delivery log." If you send too many tests in a short time, it says: "Too many tests in a short time. Please try again in a few minutes." 10 tests in 10 minutes are allowed.

#### Edit

With **Edit** you change address, description and events. The dialog says: "The secret stays as it is." With **Save** you apply the change.

#### Pause and resume

With **Pause** you stop an endpoint. Open deliveries are cancelled, and it says: "Endpoint paused. Open deliveries were cancelled." The list says: "Paused on" with a date, "No events go to this address in the meantime." With **Resume** the endpoint runs again.

> [!WARNING]
>
> Events that arise during a pause are not delivered later. Anyone who needs them fetches them through the [API](https://docs.hocdoc.com/en/api/introduction.md).

#### Automatic pause

If several deliveries to an endpoint finally fail in a row (5 in a row), HocDoc pauses it on its own. The list then shows "Paused automatically" and says: "Paused automatically on" with a date and the number of failed deliveries in a row. Check the receiver and then choose **Resume**.

#### Regenerate the secret

If you have lost the secret, you choose **Regenerate secret** and confirm with **Regenerate**. The dialog says: "The current secret stops working immediately. Your receiver needs the new secret, otherwise it will reject the calls. We retry rejected messages automatically until you have entered the new secret there." The old and the new secret never work at the same time. Afterwards the "New secret" dialog shows the new secret once, as when adding. Enter it in your system.

#### Delete an endpoint

Choose **Delete** and confirm in the "Delete endpoint" dialog. The dialog says: "\[Address] will no longer receive any events. This endpoint's delivery log is deleted too. This cannot be undone."

### Delivery log

The "Delivery log" card shows what went to your endpoints and to your channels for notifications: "The last 50 deliveries. Entries are deleted after 30 days." With **Refresh** you reload the list. As long as nothing has been delivered, it says: "No delivery yet".

Each entry names the event, the address ("on" with the address's name), date and time, the status and the number of attempts. For a response it also shows "Status" with the code and the duration in milliseconds. The status is one of:

| Status | Meaning |
| - | - |
| **Delivered** | Your system answered with a success code. |
| **Pending** | The delivery is still running. The entry says whether the first attempt is pending or when the next attempt comes ("Attempt 2 of 8 failed. Next attempt on" with a date). |
| **Failed** | All attempts failed. The entry names the reason. |

An attempt counts as failed if your system does not answer with a success code within 10 seconds. HocDoc tries up to 8 times in about a day.

Typical reasons the entry names:

* "No response within 10 seconds."
* "The receiver responded with an error."
* "The encrypted connection could not be established. Check the certificate of the receiver."
* "The receiver redirected. Redirects are not followed."
* "Cancelled because the endpoint was paused."
* "Not queued because too many deliveries were already open for this endpoint."

#### Send again

For a failed delivery you choose **Send again**. Afterwards it says: "The delivery is being sent again." The call has the same content and the same ID as before. A delivery can be sent again up to 5 times. If the endpoint is paused, you resume it first. Otherwise it says: "The endpoint is paused. Resume it first." If the endpoint already has 1000 open deliveries, **Send again** is rejected. Then it says: "This endpoint already has 1000 deliveries waiting. Please try again later."

### Public API card

All roles see this card. It says: "Read offers and their timeline. With write permission, also create, send and withdraw offers. Every request needs an API key." It shows:

| Entry | Content |
| - | - |
| **Base URL** | The API's address |
| **Authentication** | The `Authorization` header with the `Bearer` scheme and the key |
| **Limit** | 120 requests per minute per API key, 300 per IP address |
| **Example** | A call with curl |
| **OpenAPI description** | Link to the machine-readable description |

### Language of new offers

The "Language of new offers" card sets which language new offers start in: Deutsch or English. Under **Language** you choose the language and save with **Set language**. Owners and admins change the default, all others see the value locked. The default only applies to new offers. Below the selection is the note "This only applies to offers. You set the app's own language under Account." with a link to the "Account" tab. For a draft, the language changes in the builder. Everything about it is under [Language per offer](https://docs.hocdoc.com/en/guides/language-per-offer.md).

## Approvals

The "Approvals" tab is part of the Team plan. On other plans it shows the note "Approvals are part of the Team plan", and a saved rule only applies again once the workspace is on the Team plan. The "Approval before sending" card sets when a member may only send an offer after an approval. Owners and admins change the rule, all other roles see it locked. There they also set how many approvals a send needs: one or two. Below is the "Open requests" list. How approvals work is described under [Approval before sending](https://docs.hocdoc.com/en/guides/team-and-roles.md#approval-before-sending).

## Audit log

The "Audit log" tab shows who changed what and when in the team and in the settings. Only owners and admins see it, and it belongs to the Team plan. On other plans it says "The audit log is part of the Team plan": entries already arise now and appear with the Team plan. Entries are kept for 365 days.

The audit log records:

* **Team:** member added, role changed, owner role changed, member removed, workspace left. Invitations sent, withdrawn and accepted (the invitation's address is shortened, such as `m…@example.com`).
* **Approvals:** approval rule changed, approval granted, rejected and revoked (without a comment), sections locked in templates and lock removed.
* **Domains:** domain and sender domain added, active and removed.
* **API:** API key created (with permission) and revoked, webhooks added, changed, paused, resumed, deleted and secret renewed.
* **Integrations:** Slack and Microsoft Teams connected, changed, paused, resumed and disconnected, CRM connections connected and disconnected.
* **Settings:** workspace renamed, plan, language, time zone, currency and baseline changed, brand, sender details and follow-up rules changed.

Each row has the columns **Time**, **Person**, **Action** and **Details**. The person is shown with their name from back then. Changes without a session, for example by background jobs, appear as "System". Secrets, key values and recipient data are not in the audit log.

With the filters **Period**, **Person** and **Area** (Team, Approvals, Domains, API, Integrations, Settings) you narrow the list, and **Reset filters** resets it. **Older entries** loads more. **Export as CSV** saves the filtered list (at most 5 exports in 10 minutes). The audit log cannot be changed or deleted.

## Account

The "Account" tab only concerns your own account and is open to all roles.

### Profile

In the "Display name" field you set how you appear in the team and in the app (2 to 120 characters). The app displays the email address. It cannot be changed there.

### Interface language

The "Language" card sits between Profile and Password. Under **Interface language** you choose "Deutsch" or "English" and save with **Save**.

* The choice belongs to your account. It applies in every browser and on every device as soon as you sign in: after signing in, the app takes over your account's language. It stays after signing out. A cookie of this browser additionally remembers it.
* On the sign-in pages the same choice appears small in the footer. If you are signed in there, it saves the language in the account.
* If you have never chosen, HocDoc suggests your browser's language if it is German or English. Otherwise German applies. The suggestion sets nothing, and your choice takes precedence.
* The emails to you as the sender (first open, acceptance, answers in the onboarding form, countersignature pending) arrive in your account's language. Without a choice they are in German.
* The team invitation email arrives in the language of the person who invites. The page on which the invited person accepts the invitation follows the language they chose there, otherwise their browser.

**What becomes English:** the interface of the app, sign-in and onboarding with their messages, also the date fields and calendars. Dates then follow English notation (month before day, 12-hour clock as customary), and so do amounts (for example `€1,500.00`). In money fields, the comma then counts as the thousands separator and the period as the decimal separator.

**What does not depend on the interface:** Everything the recipient of an offer sees depends on the [offer's language](https://docs.hocdoc.com/en/guides/language-per-offer.md): the offer page, the emails to recipients and signers, the offer PDF and the certificate. The messages to Slack and Teams stay in German.

The labels in this documentation are the English ones.

### Change password

You enter "Current password", "New password" (at least 6 characters) and "Repeat new password" and choose **Change password**. The new password must differ from the current one. If your account has two-factor authentication, the field "Code from the authenticator app" is added.

If you have forgotten your password, use "Forgot password?" on the sign-in page.

### Two-factor authentication

With two-factor authentication, the app asks at sign-in for a code from an authenticator app on your phone in addition to the password. The card shows "Active" or "Not active".

**Set up**

**1. Choose Set up**

Choose **Set up**. The card shows a QR code and a key to type in.

**2. Scan the QR code**

Scan the QR code with an authenticator app (for example Google Authenticator, 1Password or Authy). If that does not work, type the key into the app. It is only shown now.

**3. Enter the code**

Enter the 6-digit code from the app in "Code from the authenticator app" and choose **Activate**. With **Cancel** you abort the setup.

After activating, all other devices are signed out. If that does not work, the app points it out and you use "Sign out on all devices".

Right afterwards the card shows your recovery codes (see below).

**When signing in**

After the password, the "Two-factor confirmation" page appears. You enter the code and choose **Confirm**. After too many attempts in a short time, the app reports "Too many attempts." and names the waiting time. Without access to the authenticator app, you choose "Use a recovery code" (see below).

**Disable**

Choose **Disable**, enter a current code and confirm with **Disable**. This always requires a fresh code. Afterwards the password is enough to sign in again, and all other devices are signed out. Your recovery codes expire in the process.

**Recovery codes**

Recovery codes are a second way into the account if you no longer have access to your authenticator app.

* **When they are created:** Right after you activate two-factor authentication, the app creates ten codes. Each code has 16 characters and is shown in groups of four.
* **One-time display:** The "Your recovery codes" section shows the codes only now. The app stores only a check value, not the codes themselves. Each code works once. Keep the codes separate from your phone.
* **Copy:** **Copy** puts all codes on the clipboard.
* **Text file:** **Download as text file** saves the file `hocdoc-wiederherstellungscodes.txt`. It is created in your browser and contains the codes, your account's address, the date and a short note on use.
* **Finish:** With **I have saved the codes** you close the display. Afterwards the same codes cannot be shown again.
* **State:** The "Two-factor authentication" card has the "Recovery codes" section. It shows how many codes are left, for example "7 of 10 left."
* **Generate new codes:** With **Generate new codes** you replace all codes with ten new ones. The app asks once beforehand: "The previous codes will stop working." Confirm with **Generate new codes** or choose **Cancel**. Afterwards the card shows the new codes once, as after activating. An email "New recovery codes created" goes to your account's address, in your account's language. It never contains a code.
* **Accounts with two-factor authentication from before:** If your account has had two-factor authentication for a while, there are no codes yet. The section then says: "This account has no recovery codes. Generate some so you can get into your account even without your phone." With **Generate codes** you create them, without a confirmation.

**Redeem a code**

**1. Choose a recovery code**

On the "Two-factor confirmation" page, choose the link "Use a recovery code". The page is then called the same.

**2. Enter the code**

Enter one of your codes in the **Recovery code** field and choose **Redeem code**. Upper and lower case, spaces and hyphens do not matter. With "Enter the code from the authenticator app" you return to the normal prompt.

**3. Sign in again**

The app removes two-factor authentication, signs out all devices and takes you to the sign-in. There it says: "Two-factor authentication has been removed and all devices have been signed out. Sign in again and set it up again in your account settings."

What applies afterwards:

* The redeemed code is used up, and the remaining codes expire with the two-factor authentication. The password is enough to sign in again.
* An email with the subject "Recovery code used for HocDoc" and the button "Reset password" goes to your account's address. It never contains a code.
* If you set up two-factor authentication again, you get new codes.
* Rarely, another factor of your account cannot be removed safely. Then the sign-in says in red: "The recovery code was redeemed and all devices have been signed out. Another factor on your account could not be removed reliably. If sign-in still asks for a code, write to [support@hocdoc.com](mailto:support@hocdoc.com)."

Messages when redeeming:

| Message | When |
| - | - |
| "Please enter the complete recovery code (16 characters)." | The input does not have 16 characters in the right format. |
| "The code is incorrect or has already been used." | The code matches no unused code. The message is the same for every account. |
| "Too many attempts. Wait" with a number of minutes "and then try again." | See lockout. |
| "The recovery didn't work. Your code is still valid. Sign in and try again." | Appears on the sign-in page when a step failed. The code is not used up. |
| "The recovery was interrupted. Sign in. If you're still asked for a code, wait two minutes and then try again." | Appears on the sign-in page when it is not clear whether the process went through. |

**Lockout after failed attempts**

After 5 wrong codes within 15 minutes, the app locks redeeming for 15 minutes. During the lockout it also rejects a correct code. The lockout counts separately from the code from the authenticator app: the normal code keeps working in the meantime.

> [!WARNING]
>
> If you have neither access to the authenticator app nor a recovery code, write to [support@hocdoc.com](mailto:support@hocdoc.com). Two-factor authentication is removed as soon as it is verified that the account belongs to you.

### Sessions

With "Sign out" in the account menu at the bottom left, you only end the session on this device. With **Sign out on all devices** you end the sessions on all your devices, this one included. You confirm in a dialog and then sign in again everywhere.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.