Connect-PowerDMARC
SYNOPSIS
Establishes a connection to the PowerDMARC API for the current session.
SYNTAX
Connect-PowerDMARC [-ApiToken] <SecureString> [-Mode <String>] [-AccountId <Int32>] [-BaseUri <String>]
[-PassThru] [-ShowBanner <Boolean>] [-ProgressAction <ActionPreference>] [<CommonParameters>]
DESCRIPTION
Stores the PowerDMARC API base URI, operating mode and Personal Access Token (PAT) for the current session so that other PowerDMARC module cmdlets (e.g. Get-PDDomain, Get-PDHostedSPF) can call the API without repeating authentication.
PowerDMARC does not expose a username/password login endpoint. Tokens are generated manually in the PowerDMARC console under API Settings > Personal Access Tokens (or, for MSSP administrators, API Settings > Manage API Tokens) and are sent as a Bearer token on every subsequent request.
PowerDMARC exposes two distinct API surfaces on the same host, rooted at different paths:
- Default (End User API), rooted at /api/v1: operates on the domains that belong to
the token's own account, e.g.
`GET /domains/
{domainId}`, `GET /hostedspf/{domainId}`. - Reseller (PowerDMARC's MSSP API), rooted at /api/v1/mssp: operates on domains
belonging to the reseller's customer accounts and requires an AccountId on most
calls, e.g.
`GET /accounts/
{accountId}/domains/{domainId}`, `GET /hosted/spf/{domainId}` (both relative to the /mssp root). -Mode determines which root the stored connection resolves to; other PowerDMARC cmdlets in this module build their relative paths off of it accordingly.
EXAMPLES
EXAMPLE 1
$token = Read-Host -AsSecureString -Prompt 'PowerDMARC API token'
Connect-PowerDMARC -ApiToken $token
EXAMPLE 2
Connect-PowerDMARC -ApiToken (ConvertTo-SecureString $env:POWERDMARC_TOKEN -AsPlainText -Force) -Mode Reseller -AccountId 42
PARAMETERS
-ApiToken
The Personal Access Token generated in the PowerDMARC console.
Type: SecureString
Parameter Sets: (All)
Aliases: Token, PersonalAccessToken, PAT
Required: True
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Mode
The API surface to use: Default (default) for the End User API, or Reseller for PowerDMARC's MSSP API. Determines which endpoint layout other PowerDMARC cmdlets in this module call. The earlier names Consumer and MSSP are still accepted as aliases for Default and Reseller, respectively.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: Default
Accept pipeline input: False
Accept wildcard characters: False
-AccountId
Reseller mode only. The default MSSP customer account ID to use on calls that don't specify one explicitly (e.g. Get-PDDomain -AccountId). Ignored in Default mode.
Type: Int32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False
-BaseUri
The PowerDMARC host/root to call. Defaults to https://app.powerdmarc.com. MSSP resellers typically have their own branded portal host instead (e.g. reseller.powerdmarc.com) -- pass that here. Accepts a bare host, a host with scheme, or a full API root; normalized as follows: a missing scheme defaults to https://, and a missing /api/vN path defaults to /api/v1. In Reseller mode, /mssp is then appended. Do not include /mssp yourself.
Examples of accepted input, all resolving the same way in Reseller mode: reseller.powerdmarc.com -> https://reseller.powerdmarc.com/api/v1/mssp https://reseller.powerdmarc.com -> https://reseller.powerdmarc.com/api/v1/mssp https://reseller.powerdmarc.com/api/v1 -> https://reseller.powerdmarc.com/api/v1/mssp
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: App.powerdmarc.com
Accept pipeline input: False
Accept wildcard characters: False
-PassThru
Return the connection object in addition to storing it for the session.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-ShowBanner
Whether to print the connection banner (mode, base URI, and a Reseller account-selection hint when applicable) after connecting. Defaults to $true; pass -ShowBanner:$false to suppress it, e.g. in unattended scripts.
Type: Boolean
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: True
Accept pipeline input: False
Accept wildcard characters: False
-ProgressAction
Fill ProgressAction Description
Type: ActionPreference
Parameter Sets: (All)
Aliases: proga
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.