Integrations
How integrations work
Vaks PM is API-first: the web application consumes the same public REST API that third-party integrations do. Every integration is therefore one of four shapes, and knowing which one you are dealing with tells you where the configuration lives and where to look when it breaks.
Identity, inbound
An external directory tells Vaks PM who exists. Users and agents are created or suspended from outside. Configured on both sides.
Events, outbound
Vaks PM calls out when something happens: webhooks, notification email, audit forwarding to a SIEM. Configured here, received there.
Callbacks, inbound
An external system calls Vaks PM: signed CI results, ticketing connectors, agent registration. Authenticated by shared secret or scoped API key.
Delegated access
A person or an AI assistant acts through the API on a user's behalf, bounded by scopes: API tokens and the MCP connector.
Two rules hold across all of them. Permissions are always enforced server-side — an integration never gains rights the underlying identity does not already have, and scopes only ever narrow them. And every integration is optional: Vaks PM runs fully self-hosted with no outbound dependency, so each one below is something you switch on deliberately.
Before you start
Three things are worth settling before configuring anything, because each has bitten a first-time setup:
- Know who holds the rights on the far side. Most of these guides need an administrator of the other system — tenant-wide consent in Entra, repository admin in GitHub. That is often a different person, and often the long pole. Each guide states both sides in its prerequisites.
- Note every secret's expiry. Client secrets, signing secrets and API tokens all expire. Vaks PM warns 14 days ahead for the tokens it issues, but it cannot know when a secret held in Entra or GitHub lapses. An integration that "stopped working for no reason" months later is nearly always an expired credential.
- Test in a non-production organization first if you run several. Identity integrations in particular can suspend real users when a mapping is wrong.
Identity & provisioning
Who can sign in, and how accounts are created and retired.
| Integration | What it gives you | Set up on the far side | Guide |
|---|---|---|---|
| Single sign-on — OIDC Module License | Sign-in through Microsoft Entra ID, Google Workspace, Okta, Keycloak or any compliant provider, with optional account creation on first sign-in and group-to-role mapping. | App registration, redirect URI, groups claim | Read the guide → |
| Single sign-on — SAML 2.0 Module License | Sign-in through any SAML identity provider — Entra, Google Workspace, AD FS, Okta, Keycloak — for organizations that cannot use OIDC. | Service-provider metadata, signing certificate, attribute statements | Read the guide → |
| SCIM 2.0 provisioning Module License | Your directory creates, updates and deactivates users, and keeps teams in step with groups. | Provisioning app, tenant URL, bearer token | Read the guide → |
AI agents
Vaks PM treats AI agents as first-class actors: an agent is an account with a mandatory human owner, a trust level, an explicit capability list, and full audit attribution. These integrations bring agent identities in and verify what they produce.
| Integration | What it gives you | Set up on the far side | Guide |
|---|---|---|---|
| Agent directories Module | Mirror agent identities from Microsoft Entra Agent ID, or let a platform register its agents by API. Imported agents arrive read-only, owned by a human, and without credentials. | App registration with AgentIdentity.Read.All — or nothing at all, for the inbound API | Read the guide → |
| Agent authentication Module License | How an activated agent obtains its short-lived token without a distributed secret — federation (the platform signs the token, exchanged per RFC 8693) or a self-rotating machine credential. Covers Kubernetes, Entra (Copilot Studio, Foundry) and GitHub Actions. | A declared trusted issuer, or one machine credential issued once | Read the guide → |
| CI verification Module License | Signed build results corroborate what an agent claims about its own work, so an approval rests on evidence rather than self-attestation. | Webhook with an HMAC shared secret, from GitHub or any CI able to sign a payload | Read the guide → |
| AI assistant connector (MCP) Module Included | An assistant such as Claude reads and updates projects on a user's behalf, bounded by that user's own permissions. | OAuth client registration in the assistant | Read the guide → |
| MCP — Copilot Studio (on behalf of the user) | Build a Microsoft Copilot Studio agent for Teams on top of the connector, with per-user identity — the agent borrows the rights of the person talking to it. For an agent that acts under its own identity, see “autonomous agent” below. | Pre-registered OAuth client + per-user auth + Teams distribution | Read the guide → |
| Copilot Studio — autonomous agent | Wire a Copilot Studio agent that acts under its own agent identity (owner, budgets, audit), works the agent loop and gets woken by a nudge. MCP tool via API key (X-Api-Key) + wake-up trigger. | Custom connector (PAT in X-Api-Key) + HTTP Webhook trigger | Read the guide → |
| Waking agents (nudges) | An event-driven path on top of the “pull” model: when a task becomes relevant to an agent, Vaks PM calls a signed callback URL to wake it — it then pulls and claims itself. Headers, HMAC signature, subscription contract, capacity control. | A callback URL registered by the agent (or an org key) | Read the guide → |
| AI agent cost | How an agent's cost is measured and billed: token or credit unit, the three ways the real cost is obtained (declared, measured by a gateway, estimated), the model price catalog, and where it all surfaces in the P&L and reports. | — (configured in admin) · optional client-side LLM gateway | Read the guide → |
| MCP — Claude | Connect Claude (or Claude Desktop) to the connector — the shortest path. | Paste the MCP URL, sign in (self-registers) | Read the guide → |
| MCP — ChatGPT | Connect ChatGPT to the connector via connectors / developer mode. | Paste the MCP URL, sign in (self-registers) | Read the guide → |
Events & delivery
What Vaks PM sends out when something happens.
| Integration | What it gives you | Set up on the far side | Guide |
|---|---|---|---|
| Webhooks | HMAC-signed HTTP callbacks on task, project and comment events, with retries and a delivery log. A Microsoft Teams card format is built in, for Teams and Power Automate. | A receiving endpoint, or a Teams / Power Automate connector URL | Read the guide → |
| Audit forwarding to a SIEM License | Audit events streamed as syslog (RFC 5424, TCP or TLS), or pulled by your collector from a scoped read-only API. | A syslog listener, optionally with mutual TLS | Read the guide → |
| Collaboration spaces Module License | A Microsoft Teams team, Slack channel, or Google Chat space is created automatically when a project starts, with membership kept in sync — three self-service providers, configured independently. Teams' SharePoint files can also be exposed, read-only, to both agents and project members. | Per-provider credentials (Entra app · Slack bot token · Google service account) | Read the guide → |
| Document sources | Documents living in SharePoint or Google Drive become readable from a project — by AI agents as working context, and by members from the interface. Read-only, live proxy, no copy. | Teams identity (SharePoint) · Google service account (Drive) | Read the guide → |
Tools & workflow
| Integration | What it gives you | Set up on the far side | Guide |
|---|---|---|---|
| Ticketing connectors | Log time against tickets that live in an external tool such as ServiceNow, without leaving Vaks PM and without importing the tickets as projects. | API credentials on the ticketing system | Read the guide → |
| Public REST API | Anything the web application can do, available to your own scripts and tools. Interactive reference published by the instance itself at /api/docs. | — | See API tokens below |
Configured in Admin only
These need no coordination with another system beyond a credential, so they are covered here rather than in a guide of their own.
Outgoing email (SMTP)
Under Admin → Notifications. Supply host, port, encryption and, if the relay requires it, a username and password — the password is encrypted at rest and never displayed again. Anonymous relays are supported: leave the authentication mode unset. Branding (logo, accent colour, sender and reply-to addresses) is configured in the same place, as are quiet hours and digest scheduling.
Press Send test email before relying on it. If your relay filters by source address, allowlist the instance's outbound IP; some providers reject on the envelope sender rather than the credential, which surfaces as an authentication failure that no password change will fix.
API tokens
Two kinds, and the difference matters:
- Personal access tokens (
vaks_pat_…) act as the user who created them. Effective rights are that user's permissions intersected with the token's scopes — so a token can only ever be narrower than its owner, even if the owner is an administrator. - Organization keys (
vaks_org_…) are service identities for machine-to-machine use, attributed in the audit log to the administrator who created them.
Both are created under Admin → API keys (organization) or in your account options (personal). The secret is shown once. An expiry is mandatory and capped at two years — there are no permanent tokens — and a reminder email goes out 14 days before one lapses. Tokens only ever reach the public API surface; they are rejected on the application's private routes.
Backup alerting
Host-side backup scripts post to a dedicated endpoint so a failed backup raises a critical audit entry, an email to administrators and a webhook. It is authenticated by a shared secret header, configured with the backup scripts themselves — see Operations.
Permissions needed
Which Vaks PM permission gates each integration's configuration screen.
| Permission | Held by | Covers |
|---|---|---|
org:manage | Organization administrators | Single sign-on, SCIM, organization‑wide webhooks, audit forwarding, organization API keys, notifications |
agent:manage | Organization administrators, and users holding the orthogonal AI administrator grant | Agents, agent directories, CI verification, agent policies |
finance:manage | Finance roles | Rates and budgets, including agent billing rates |
The AI administrator grant exists so that whoever runs your AI programme can manage agents end to end without becoming a full administrator. It stacks on any role and is limited to the agent surface — it grants no access to finance, clients or organization settings.
Webhooks are the one integration with a self-service path: org‑wide webhook administration needs org:manage, but a project's own webhooks can also be managed by its project manager or team lead (project:view plus the webhooks.managePolicy organization policy), without org:manage.
General troubleshooting
Patterns that recur across integrations, worth checking before opening a specific guide:
- It worked, then stopped. Suspect an expired credential first — client secret, signing secret or API token. This accounts for most integrations that fail without any change on either side.
- Permission granted but still refused. On Microsoft platforms, a permission added to an app registration does nothing until an administrator grants tenant-wide consent. Check that the status column reads Granted, not merely that the permission is listed.
- Outbound calls time out. A self-hosted instance may sit behind an egress proxy or firewall. Anything reaching Microsoft Graph, a CI provider or a webhook endpoint needs that path open; Vaks PM never assumes unrestricted outbound access.
- Nothing arrives, but nothing errors either. Check the delivery log — webhooks record every attempt with the response — and the audit log, which records outcomes the on-screen confirmation sometimes omits.
- Some error messages are in French regardless of your interface language, when they originate server-side. The specific guides reproduce them verbatim so you can match on the exact string.
Related: product & features for what each capability does conceptually · encryption & keys for how integration secrets are protected · operations for day-2 concerns.