🚀 [Feature]: Connect by site name; add accessible-resources and v1/v2 map

Connect-Confluence now takes -Site (name/host/URL, resolved to a cloud ID via the public tenant_info endpoint) or -CloudId (faster, direct); it builds the api.atlassian.com/ex/confluence/<cloudId> gateway base internally. Adds Get-ConfluenceAccessibleResource (lists sites/cloudIds/scopes a bearer token can reach) and an internal v1/v2 API-path map (v1 -> /wiki/rest/api, v2 -> /wiki/api/v2) usable via Invoke-ConfluenceRestMethod -ApiVersion. Integration test connects with -Site from CONFLUENCE_SITE.

Author: MariusStorhaug

.github/workflows/Process-PSModule.yml

@@ -44,7 +44,7 @@ jobs:
       # Non-secret configuration the module's tests need, exposed as environment variables (not masked).
       TestVariables: >-
         {
-        "CONFLUENCE_API_BASE_URI": ${{ toJSON(vars.CONFLUENCE_API_BASE_URI) }},
+        "CONFLUENCE_SITE": ${{ toJSON(vars.CONFLUENCE_SITE) }},
         "CONFLUENCE_USERNAME": ${{ toJSON(vars.CONFLUENCE_USERNAME) }},
         "CONFLUENCE_SPACE_KEY": ${{ toJSON(vars.CONFLUENCE_SPACE_KEY) }}
         }

src/functions/public/API/Invoke-ConfluenceRestMethod.ps1

@@ -40,9 +40,16 @@ function Invoke-ConfluenceRestMethod {
     param(
         # The API path beginning with '/wiki/', e.g. '/wiki/api/v2/pages'.
         # A full absolute URL is also accepted (used when following pagination links).
+        # When -ApiVersion is supplied this is treated as a path relative to that
+        # API family's root (e.g. -ApiVersion v2 -ApiEndpoint 'spaces').
         [Parameter(Mandatory)]
         [string]$ApiEndpoint,
 
+        # Optional API family. Uses the internal map to prepend the version prefix
+        # (v1 -> /wiki/rest/api, v2 -> /wiki/api/v2) to a relative -ApiEndpoint.
+        [ValidateSet('v1', 'v2')]
+        [string]$ApiVersion,
+
         # The HTTP method. Defaults to GET.
         [ValidateSet('GET', 'POST', 'PUT', 'DELETE')]
         [string]$Method = 'GET',
@@ -67,6 +74,11 @@ function Invoke-ConfluenceRestMethod {
         throw "The -All switch follows pagination and is only valid for GET requests, not $Method."
     }
 
+    # Resolve a relative endpoint against the internal v1/v2 map when a version is given.
+    if ($ApiVersion -and $ApiEndpoint -notmatch '^https?://') {
+        $ApiEndpoint = '{0}/{1}' -f $script:Confluence.ApiPaths[$ApiVersion], $ApiEndpoint.TrimStart('/')
+    }
+
     $resolved = Resolve-ConfluenceContext -Context $Context
     $token = Resolve-ConfluenceToken -Token $resolved.Token
     $pair = '{0}:{1}' -f $resolved.Username, $token

src/functions/public/Auth/Connect-Confluence.ps1

@@ -7,16 +7,26 @@ function Connect-Confluence {
         .DESCRIPTION
         Validates the supplied credentials with a lightweight authenticated call,
         stores them as a named context (the token is kept as a SecureString), and
-        records the context as the module default. A token that authenticates but
-        lacks the read:space scope still connects (with a warning).
+        records the context as the module default. Supply the site with -Site (a
+        name such as 'msxorg', a host, or a URL) and the cloud ID is resolved
+        automatically; or pass a known -CloudId directly to skip the lookup. A
+        token that authenticates but lacks the read:space scope still connects
+        (with a warning).
 
         .EXAMPLE
         ```powershell
         $token = Read-Host -AsSecureString
-        Connect-Confluence -ApiBaseUri $uri -Username $user -Token $token -SpaceKey 'DOCS'
+        Connect-Confluence -Site 'msxorg' -Username $user -Token $token -SpaceKey 'DOCS'
         ```
 
-        Connects with a scoped token and stores the profile with 'DOCS' as the default space.
+        Resolves the cloud ID for msxorg.atlassian.net, connects, and stores 'DOCS' as the default space.
+
+        .EXAMPLE
+        ```powershell
+        Connect-Confluence -CloudId 'fff64f40-36b7-4578-92be-b9d9b6b17658' -Username $user -Token $token
+        ```
+
+        Connects directly with a known cloud ID, skipping the site lookup.
 
         .LINK
         https://psmodule.io/Confluence/Functions/Auth/Connect-Confluence/
@@ -27,12 +37,18 @@ function Connect-Confluence {
         .LINK
         https://developer.atlassian.com/cloud/confluence/scopes-for-oauth-2-3LO-and-forge-apps/
     #>
-    [CmdletBinding(SupportsShouldProcess)]
+    [CmdletBinding(SupportsShouldProcess, DefaultParameterSetName = 'Site')]
     [OutputType([pscustomobject])]
     param(
-        # The Confluence API-gateway base URI, for example `https://api.atlassian.com/ex/confluence/<cloudId>`.
-        [Parameter(Mandatory)]
-        [string]$ApiBaseUri,
+        # The Confluence Cloud site: a name (`msxorg`), a host (`msxorg.atlassian.net`),
+        # or any URL on the site. The cloud ID is resolved automatically.
+        [Parameter(Mandatory, ParameterSetName = 'Site')]
+        [string]$Site,
+
+        # The Confluence Cloud ID - a faster alternative to -Site that skips the lookup.
+        # Find it with `ConvertTo-ConfluenceCloudId` or `Get-ConfluenceAccessibleResource`.
+        [Parameter(Mandatory, ParameterSetName = 'CloudId')]
+        [string]$CloudId,
 
         # The service-account user (email) used for HTTP Basic authentication.
         [Parameter(Mandatory)]
@@ -52,6 +68,13 @@ function Connect-Confluence {
         [switch]$PassThru
     )
 
+    if ($PSCmdlet.ParameterSetName -eq 'Site') {
+        # Resolve a site name/host/URL to its cloud ID via the public tenant_info endpoint.
+        $CloudId = ConvertTo-ConfluenceCloudId -Site $Site
+    }
+    # The scoped-token gateway base is always api.atlassian.com/ex/confluence/<cloudId>.
+    $ApiBaseUri = 'https://api.atlassian.com/ex/confluence/{0}' -f $CloudId
+
     if ([string]::IsNullOrEmpty($Name)) {
         # api.atlassian.com is shared by every Confluence Cloud site, so the host
         # alone is not unique. Include the trailing base-URI path segment (the

src/functions/public/Auth/Get-ConfluenceAccessibleResource.ps1

@@ -0,0 +1,62 @@
+#SkipTest:FunctionTest:Calls the public accessible-resources endpoint with a bearer token; covered by integration tests.
+function Get-ConfluenceAccessibleResource {
+    <#
+        .SYNOPSIS
+        List the Atlassian sites (resources) a token can reach.
+
+        .DESCRIPTION
+        Calls `https://api.atlassian.com/oauth/token/accessible-resources` with the
+        token as a bearer credential and returns one object per accessible site.
+        Each result exposes the site `id` (which is the cloud ID used in the
+        API-gateway base URI), the site `url`, the `name`, and the `scopes` granted
+        to the token for that site. Use it to discover the cloud ID and confirm the
+        granted scopes before connecting.
+
+        .EXAMPLE
+        ```powershell
+        $token = Read-Host -AsSecureString
+        Get-ConfluenceAccessibleResource -Token $token
+        ```
+
+        Lists every site the token can reach, with the cloud ID (`id`), URL and granted scopes.
+
+        .EXAMPLE
+        ```powershell
+        (Get-ConfluenceAccessibleResource -Token $token | Where-Object url -match 'msxorg').id
+        ```
+
+        Returns the cloud ID for the msxorg site from the token's accessible resources.
+
+        .OUTPUTS
+        System.Management.Automation.PSObject
+
+        .LINK
+        https://psmodule.io/Confluence/Functions/Auth/Get-ConfluenceAccessibleResource/
+
+        .LINK
+        https://developer.atlassian.com/cloud/confluence/oauth-2-3lo-apps/#3--make-calls-to-the-api-using-the-access-token
+    #>
+    [CmdletBinding()]
+    [OutputType([object])]
+    param(
+        # The scoped Atlassian API token as a SecureString.
+        [Parameter(Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName)]
+        [securestring]$Token
+    )
+
+    process {
+        $bearer = Resolve-ConfluenceToken -Token $Token
+        $headers = @{
+            Authorization = "Bearer $bearer"
+            Accept        = 'application/json'
+        }
+        $uri = 'https://api.atlassian.com/oauth/token/accessible-resources'
+        Write-Verbose "Listing accessible resources from [$uri]."
+
+        try {
+            Invoke-RestMethod -Uri $uri -Headers $headers -Method Get -ErrorAction Stop
+        } catch {
+            throw "Failed to list accessible resources from [$uri]: $($_.Exception.Message)"
+        }
+    }
+}

src/variables/private/Confluence.ps1

@@ -1,5 +1,13 @@
 $script:Confluence = [pscustomobject]@{
     ContextVault  = 'PSModule.Confluence'
+    # The API-gateway base is https://api.atlassian.com/ex/confluence/<cloudId>. These are the two
+    # Confluence API families that hang off it; the map keeps the version prefixes in one place.
+    #   v2 -> <base>/wiki/api/v2/...   (e.g. /wiki/api/v2/spaces)
+    #   v1 -> <base>/wiki/rest/api/... (e.g. /wiki/rest/api/content)
+    ApiPaths      = @{
+        v1 = '/wiki/rest/api'
+        v2 = '/wiki/api/v2'
+    }
     DefaultConfig = @{
         ID             = 'Module'
         DefaultContext = ''

tests/Confluence.Tests.ps1

@@ -40,6 +40,7 @@ Describe 'Confluence' {
                     'Get-ConfluenceSpace'
                     'Get-ConfluenceSiteInfo'
                     'ConvertTo-ConfluenceCloudId'
+                    'Get-ConfluenceAccessibleResource'
                     'New-ConfluencePage'
                     'Get-ConfluencePage'
                     'Set-ConfluencePage'
@@ -71,17 +72,17 @@ Describe 'Confluence' {
 
     # Integration tests run only when live credentials are provided. The calling workflow supplies
     # them through Process-PSModule's TestSecrets (CONFLUENCE_API_TOKEN, masked) and TestVariables
-    # (CONFLUENCE_API_BASE_URI, CONFLUENCE_USERNAME, CONFLUENCE_SPACE_KEY), which are exposed as
-    # environment variables. They are skipped locally and wherever the API token is not available.
+    # (CONFLUENCE_SITE, CONFLUENCE_USERNAME, CONFLUENCE_SPACE_KEY), which are exposed as environment
+    # variables. They are skipped locally and wherever the API token is not available.
     Context 'Integration' -Skip:([string]::IsNullOrEmpty($env:CONFLUENCE_API_TOKEN)) {
         BeforeAll {
             $secureToken = ConvertTo-SecureString -String $env:CONFLUENCE_API_TOKEN -AsPlainText -Force
             $connectParams = @{
-                ApiBaseUri = $env:CONFLUENCE_API_BASE_URI
-                Username   = $env:CONFLUENCE_USERNAME
-                Token      = $secureToken
-                SpaceKey   = $env:CONFLUENCE_SPACE_KEY
-                Name       = 'ci'
+                Site     = $env:CONFLUENCE_SITE
+                Username = $env:CONFLUENCE_USERNAME
+                Token    = $secureToken
+                SpaceKey = $env:CONFLUENCE_SPACE_KEY
+                Name     = 'ci'
             }
             Connect-Confluence @connectParams
         }