Configuring ActivityPulse

The Settings area is where you configure your ActivityPulse organization — users and roles, LLM providers, data source connections, sync schedules, and email delivery. Access it from the sidebar by clicking Settings.

What you can see and change depends on your role:

Role	Settings access
Owner	Full access to all settings, including user management and organization deletion
Admin	All settings except promoting users to Owner or deleting the organization
Viewer	Read-only access; can configure their own email report preferences

Server Configuration

Some settings are configured as environment variables by the system administrator rather than through the web interface.

Variable	Required	Default	Description
`DATABASE_URL`	Yes	—	PostgreSQL connection string
`JWT_SECRET`	Yes	—	Secret key used to sign authentication tokens
`APP_URL`	No	Derived from request	Base URL of the ActivityPulse instance (e.g. `https://activitypulse.example.com`). Used to construct user invitation links and SSO redirect URIs. When not set, the server falls back to the `Origin` or `Referer` header from the browser request.
`HOST`	No	`0.0.0.0`	Network interface the server listens on
`PORT`	No	`8080`	Port the server listens on

Recommendation: Set APP_URL in production. It is required for SSO and ensures invitation links always point to the correct address regardless of how the request reaches the server (e.g. behind a reverse proxy).

Where to set environment variables

The configuration file location depends on how ActivityPulse was deployed:

Deployment method	Configuration file	Apply changes
Debian package	`/etc/activitypulse/activitypulse.conf`	`sudo systemctl restart activitypulse`
Tarball	`/opt/activitypulse/activitypulse.conf`	`sudo systemctl restart activitypulse`
Docker	`.env` next to `docker-compose.yml` (typically `/opt/activitypulse/.env`)	`docker compose up -d`

The installer automatically generates DATABASE_URL, JWT_SECRET, and APP_URL during first-time setup. APP_URL is auto-detected from the machine’s hostname — update it to match your actual domain or URL if you use DNS or TLS.

User Management

Navigate to Settings > Users to manage who has access to your organization.

A fresh deployment ships with public sign-up enabled so the first administrator can register an account and bootstrap their organization. As soon as that first registration succeeds, ActivityPulse automatically disables public sign-up — additional users can only join through invitations from then on.

Owners can review or override this behaviour from Settings > General, in the System card. The Allow public sign-up switch reflects the current state and lets owners re-open registration if a second bootstrap is ever needed (rare; most deployments leave it disabled). When public sign-up is disabled, the Sign up link on the login page is hidden and the /register API returns 403.

Inviting users

The primary way to add new people is by invitation. Click Invite user, enter the person’s email address, display name, and select a role. ActivityPulse sends an email with a unique invite link that expires after 7 days.

Prerequisite: Email delivery must be configured before you can send invitations. See Email Settings below.

The Users page shows pending invitations alongside active users. For each pending invite you can:

Resend — generates a fresh token and sends a new email (useful if the original expired)
Cancel — revokes the invitation so the link can no longer be used

When the recipient clicks the invite link, they are guided through account creation and are automatically added to your organization with the role you selected.

Inviting existing teammates as users

If someone is already a Teammate, you can invite them by selecting the teammate from the list. Click Invite User, search for the teammate, and assign a role.

Roles

ActivityPulse uses three roles with a clear permission hierarchy:

Permission	Owner	Admin	Viewer
View dashboards, activities, and summaries	Yes	Yes	Yes
Configure own email reports	Yes	Yes	Yes
Manage teammates and external IDs	Yes	Yes	No
Manage teams	Yes	Yes	No
Configure data sources	Yes	Yes	No
Change LLM, sync, and email settings	Yes	Yes	No
Add, invite, and remove users	Yes	Yes	No
Promote or demote Admins	Yes	Yes	No
Promote or demote Owners	Yes	No	No
Delete the organization	Yes	No	No

An organization must always have at least one Owner.

Team access

Users and teammates are different concepts in ActivityPulse. A user is someone who logs in to the application; a teammate is a person whose activity is being tracked across data sources. A user does not have to be a teammate, and a teammate does not need a user account. When both exist for the same person, they are linked by email address.

Teams are groups of teammates — users cannot be added to teams. From the Users page, you can scope a user’s default view to one or more teams by clicking the team access action on their row. When the user opens a dashboard, the teammate filter is pre-populated with members of those teams.

For details on creating and managing teams and teammates, see the Teammates and Teams section of the features overview.

LLM Configuration

Navigate to Settings > LLM to configure the language model that powers activity summaries.

Provider and model:

Select a provider — Anthropic (Claude) or OpenAI
Enter your API key and click Validate. ActivityPulse checks the key against the provider’s API and, on success, populates the model dropdown with available models.
Choose the model you want to use for generating summaries.

Response settings:

Setting	Range	Default	Description
Max response tokens	256 – 16,384	Provider default	Controls the maximum length of generated summaries
Debug mode	On / Off	Off	When enabled, shows the raw prompt sent to the LLM alongside the generated summary — useful for prompt tuning

Custom summary prompt:

Below the provider settings, the Summary Prompt section lets you edit the prompt template that ActivityPulse sends to the LLM when generating activity summaries. Use this to tailor the output to your organization’s tone, focus areas, or formatting preferences. A Reset to default button restores the built-in prompt at any time.

Data Sources

Navigate to Settings > Data Sources to connect ActivityPulse to the tools your team uses.

Available sources

Source	What it fetches
GitLab	Commits, merge requests, code reviews, issues, pipelines
GitHub	Pull requests, commits, issues, reviews, branches
Atlassian (Jira & Confluence)	Issues, worklogs, comments, Confluence pages and edits
Microsoft 365	Email volume, Teams calls and meetings, OneDrive/SharePoint activity, calendar events

Configuring a data source

Select a source from the list to open its configuration form. Each source requires its own credentials — typically a URL and an API token or app registration. Fill in the required fields and click Save.

For step-by-step setup instructions including required permissions and scopes, see the dedicated configuration guides:

Testing a data source

After saving, click Validate to verify that ActivityPulse can connect to the source using the credentials you provided. Validation checks authentication and basic API access — if it fails, review the error message and confirm your token, URL, and permissions.

Syncing data

Once a source is configured and validated, you can trigger a manual sync:

Fetch all — syncs every configured source at once
Fetch (per source) — syncs only the selected source

After a fetch completes, ActivityPulse reports the number of activities and signals retrieved, the duration, and any errors. For ongoing data collection, configure the automatic sync schedule under Data Sync Settings.

Data Sync Settings

Navigate to Settings > Data Sync to control how ActivityPulse fetches and retains data from your connected sources.

Setting	Range	Default	Description
Sync frequency	1 – 168 hours	24 hours	How often ActivityPulse automatically pulls new data from each source
Historical data window	1 – 365 days	30 days	How far back each sync reaches when fetching data
Data retention	1 – 365 days	90 days	How long activity data is kept before automatic cleanup

How background sync works:

ActivityPulse runs a scheduled background job at the configured frequency. Each run fetches data from all enabled sources for all teammates whose sync is active. Built-in guards prevent overlapping fetches — if a sync for a particular organization and source is already in progress, the scheduler skips it rather than starting a duplicate.

You can always trigger an immediate sync from the Data Sources settings without waiting for the next scheduled run.

Email Settings

Navigate to Settings > Email to configure how ActivityPulse sends emails. Email delivery is used for user invitations, password resets, and scheduled summary reports.

ActivityPulse supports two email transports:

Transport	Best for	Requirements
SMTP	Any email provider with SMTP access	SMTP server credentials
Microsoft Graph API	Microsoft 365 organizations	MS365 data source configured with `Mail.Send` permission

If your organization uses Microsoft 365 and has already configured the MS365 data source, the Graph API transport is recommended — it reuses your existing Azure AD app registration and bypasses SMTP authentication restrictions that many organizations enforce.

After selecting a transport and entering the required settings, use the Send test email button to verify that delivery works before relying on it for invitations or reports.

For complete setup instructions — including Office 365 SMTP configuration, app password setup, Graph API permissions, and troubleshooting — see the Email Configuration guide.

Tip: Configure email before inviting users. Without a working email transport, invitations cannot be sent.

Single Sign-On (SSO)

Navigate to Settings > SSO to allow users in your organization to sign in with their Microsoft account instead of an email and password.

Prerequisites

Before enabling SSO, two things must be in place:

Microsoft 365 data source configured — SSO reuses the Azure AD app registration (tenant ID, client ID, and client secret) from your MS365 data source plugin configuration. See Microsoft 365 plugin configuration for setup instructions.
APP_URL environment variable set — the server uses this to construct the OAuth redirect URI. See Server Configuration above.

Enabling SSO

Once the prerequisites are met, toggle Enable SSO on and click Save configuration. Users will see a Login with Microsoft button on the login page.

When a user clicks Login with Microsoft:

Single-organization deployments — the user is redirected to Microsoft sign-in immediately. No email address is needed.
Multi-organization deployments — the user must first enter their email address so ActivityPulse can identify which organization (and which Azure AD tenant) to authenticate against.

After successful authentication with Microsoft, the user is logged in automatically. The user must already have an ActivityPulse account — SSO authenticates existing users but does not create new accounts.

Azure AD app registration requirements

The Azure AD app registration used for SSO must have a redirect URI configured. Add the following URI to the app’s Authentication > Web > Redirect URIs in the Azure portal:

{APP_URL}/auth/microsoft/callback

Replace {APP_URL} with your ActivityPulse instance URL (for example, https://activitypulse.example.com).

The app registration must also have the following API permissions:

Permission	Type	Purpose
`openid`	Delegated	Sign users in
`profile`	Delegated	Read basic profile
`email`	Delegated	Read user email address
`User.Read`	Delegated	Read signed-in user profile from Microsoft Graph

These permissions are typically already granted if you have configured the MS365 data source.