sevdesk
Read and create sevdesk invoices, contacts, vouchers and bank transactions.
Connect it with: API key. sevdesk's own documentation: https://api.sevdesk.de/.
What agents can do
Connect sevdesk so the agents working your tasks can reach it. With it connected, they can:
- Find an invoice or credit note and report its status, amount and due date.
- Create draft invoices from a task's line items for a person to check and send.
- Look up or add customers and suppliers.
- List vouchers and bank transactions for a period to support bookkeeping.
Before you start
- A sevdesk plan that includes API access (sevdesk lists it from its Buchhaltung Pro plan up).
- A sevdesk user whose API token agents may use; an administrator can see each user's token under Einstellungen > Benutzer.
- A Jaah account. Anyone can add a personal secret; an organization secret needs an Org Owner or Admin.
Connect with sevdesk
Jaah connects to sevdesk with an API key, not with a sign-in button.
Connect with an API key
Find each value first:
- API token: In sevdesk, open Einstellungen (Settings) > Benutzer (Users), select the user agents should act as, and copy the API-Token shown on that user's page: 32 letters and digits. Use a user with only the rights agents need, since the token carries all of that user's rights.
Then add it to Jaah:
- In Jaah, open Secrets, select New, and pick the sevdesk card.
- Name the secret and choose who can use it.
- Fill in API token.
- Select Save. Jaah tests the secret straight away (see Test the connection).
Jaah encrypts what you type and never shows it again — not to you, and not to an admin.
Use your own OAuth app
Not used: Jaah connects to sevdesk with an API key, not through an OAuth app.
Test the connection
Select Test on the secret. Jaah calls sevdesk's API once (GET https://my.sevdesk.de/api/v1/SevUser?limit=1) with the stored values, and shows whether sevdesk accepted it, or which value sevdesk refused and the status it answered. Jaah also tests automatically when you save or reconnect.
The last result and its time stay on the secret's page, so you can see whether it still works without testing again.
Who can use it
Every secret has an owner, and the owner decides who can use it:
- Personal — only your own tasks can use it. This is the default.
- Organization — every task in the organization can use it. Only Org Owners and Admins can choose this.
- Attached to a project — every task on that project can use it, whoever started the task. See Attach a secret to a project.
More on owners and access: How secrets work.
Use it in an agent session
An agent asks for the secret with its credential_get tool, by the secret's path, when it needs it, and gets the values for that one call. The path is the owner's prefix and the secret's name:
org/<name>for an organization secret,projects/<project>/<name>for one attached to a project,me/<name>for your personal one.
A key connection hands the agent its fields: api_token.
Tell the agent in your task description which secret to use, for example “use the sevdesk secret org/sevdesk”.
Manage, rotate or disconnect
Everything is on the secret's page under Secrets:
- Rotate a key: create a new key at the vendor first, then select Replace on the secret and paste it. Revoke the old key at sevdesk once the test passes. Steps: Replace or delete a secret.
- Disconnect: select Delete. The stored values are destroyed and agents lose access on their next call. To end access at sevdesk's side too, revoke or delete the key at sevdesk.
Limitations
- The token has every right its user has and never expires; restrict what agents can do by choosing a user with fewer rights.
- Regenerating the token in sevdesk ends every connection that uses the old one, including this one.
- Whether the account runs bookkeeping system 1.0 or 2.0 changes how some endpoints behave; agents check it before writing vouchers.
- Agents can do only what the connected sevdesk account allows.
Troubleshooting
Test says sevdesk rejected the API token (401)
The token was regenerated, its user was deactivated, or it was mistyped. Copy the current token from Einstellungen > Benutzer and select Replace.
Agents get 401 although Test passed earlier
Someone regenerated the user's token in sevdesk. Copy the new one and select Replace.
An agent's request fails with 400
A list was asked for with a limit outside 1 to 1000, or a field sevdesk does not know. Ask the agent to retry with smaller pages.
Still stuck? Select Test and read the result: it names the value sevdesk refused and the status it answered.
FAQ
Can I create a separate token for Jaah?
sevdesk has one token per user. Create a sevdesk user for Jaah with only the rights agents need, and use its token.
Does Test change anything?
No. It reads one user record and discards it.
Can Jaah or an admin see the key or token?
No. Jaah stores it encrypted and never shows it again. Only the tasks allowed to use the secret receive it, at the moment they ask for it.
Can I connect more than one sevdesk account?
Yes. Add one secret per account, each with its own name, and tell the agent which one to use.