API connectors (M365, Google, Exchange)

API connectors link an organization's mail platform to Obsidian for user sync, sign-in with work accounts, clawback of delivered threats, and API-mode scanning. Add one on the organization page.

Capabilities (every connector)

Connector enabled: Master switch.
Sync users and aliases every 4 hours: Creates a user for every mailbox in the organization's domains, keeps display names and aliases current, and disables users removed from the directory. Users that already exist in another organization, and administrators, are left alone. Sync users runs it now.
Allow clawback of delivered threats: Lets administrators (Claw back button) and async-mode AI reviews move delivered messages out of mailboxes.
API mode: Every 2 minutes, new inbox mail in the scanned mailboxes is read, scanned and acted on inside the mailbox: quarantine-worthy mail is moved out (restorable with Release), tagged spam is moved to Junk. Scan mailboxes runs it now. The first run only records a starting point - it does not rescan old mail.
Let users sign in: (Microsoft 365 / Google.) Adds "Continue with Microsoft / Google" to the sign-in page. The person must already exist as a user in Obsidian (sync takes care of that).

Secret fields show stored when a value is saved; leave them blank to keep the stored value. Secrets are encrypted at rest and never shown again. Test connection checks credentials and shows what it found; the result is also kept as the connector's status. Remove connector deletes it and its credentials.

Microsoft 365

Tenant idtenant_id: Directory (tenant) ID GUID from Entra ID > Overview, or the tenant's onmicrosoft.com name.
Client idclient_id: Application (client) ID of the app registration you created for Obsidian.
Client secretclient_secret: A client secret from the app registration (Certificates & secrets). Stored encrypted; secrets expire - note the expiry date and rotate before it.
Mailboxesmailboxes: Mailboxes scanned in API mode, comma separated. Empty = every active synced user in the organization.
Quarantine folderquarantine_folder: Where clawback moves messages: recoverableitemsdeletions (hidden from the user, recoverable by admins - default), deleteditems, or junkemail.
Sso tenantsso_tenant: Tenant used for 'Continue with Microsoft' sign-in. Empty = 'organizations' (any work account; users must still exist in Obsidian).

Creating the app registration

Entra admin center › App registrations › New registration, name "Obsidian", single tenant.
API permissions › Microsoft Graph › Application permissions: User.Read.All and Mail.ReadWrite › Grant admin consent.
Certificates & secrets › New client secret; copy the value (shown once) into client_secret. Note the expiry.
Copy the Directory (tenant) ID and Application (client) ID into the connector.
For sign-in: Authentication › Add a platform › Web › redirect URI <console URL>/auth/oidc/m365/callback, and delegated permissions openid, email, profile.
Least privilege (optional): restrict Mail.ReadWrite to the scanned mailboxes with an Exchange Online RBAC for Applications scope.

Google Workspace

Admin emailadmin_email: A Google Workspace super admin the service account impersonates for directory reads.
Customercustomer: Customer ID for directory queries; my_customer (default) means the admin's own account.
Mailboxesmailboxes: Mailboxes scanned in API mode, comma separated. Empty = every active synced user.
Service account jsonservice_account_json: The whole JSON key file of the service account (paste the contents). Stored encrypted.
Oauth client idoauth_client_id: Client ID of a Google OAuth 'Web application' client, used only for 'Continue with Google' sign-in.
Oauth client secretoauth_client_secret: Secret of that OAuth client. Stored encrypted.

Creating the service account

Google Cloud console: create a project; enable the Gmail API and Admin SDK API.
IAM › Service accounts › create one, then Keys › Add key › JSON. Paste the file's contents into service_account_json.
Google Admin console › Security › Access and data control › API controls › Domain-wide delegation › Add new: the service account's client ID with the scopes
https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/gmail.modify
For sign-in: APIs & Services › Credentials › Create OAuth client ID (Web application) with redirect URI <console URL>/auth/oidc/google/callback; paste its ID and secret.

Clawback in Google moves the message to Trash; restore untrashes it and puts it back in the inbox.

Exchange (on-premises)

Ews urlews_url: Exchange Web Services endpoint, normally https://mail.<domain>/EWS/Exchange.asmx.
Ews usernameews_username: Service account with the ApplicationImpersonation role (DOMAIN\user or user@domain).
Ews passwordews_password: That account's password. Stored encrypted.
Ews authews_auth: NTLM (default, what Exchange expects) or basic.
Verify tlsverify_tls: yes / no. Choose no only when Exchange uses an internal CA the gateway does not trust.
Ldap urlldap_url: Domain controller for directory sync and user sign-in, e.g. ldaps://dc1.contoso.local:636.
Ldap bind dnldap_bind_dn: Account used to read users (can be the same service account).
Ldap passwordldap_password: Its password. Stored encrypted.
Ldap base dnldap_base_dn: Search base, e.g. DC=contoso,DC=local.
Mailboxesmailboxes: Mailboxes scanned in API mode, comma separated. Empty = every active synced user.

Preparing Exchange

Create a service account, e.g. svc-obsidian.
In the Exchange Management Shell: New-ManagementRoleAssignment -Name ObsidianImpersonation -Role ApplicationImpersonation -User svc-obsidian
EWS URL is normally https://mail.<domain>/EWS/Exchange.asmx; keep NTLM authentication.
LDAP: use LDAPS (port 636) to a domain controller. The same account can bind for directory reads.

Users of an Exchange organization sign in to the portal with their Windows password (checked against the domain controller) - no password is stored in Obsidian.

Status and errors

The connector page header shows the last activity and result (test, sync or poll). Background failures also appear under System health › Background jobs. Common causes: expired client secret (M365), missing admin consent, delegation scopes typed wrong (Google), the service account lacking impersonation rights (Exchange).