HaloAPI

1.0.1

Public/Connect-HaloAPI.ps1

#Requires -Version 7
function Connect-HaloAPI {
    <#
        .SYNOPSIS
            Creates a new connection to a Halo instance.
        .DESCRIPTION
            Creates a new connection to a Halo instance and stores this in a PowerShell Session.
        .EXAMPLE
            PS C:\> Connect-HaloAPI -URL "https://example.halopsa.com" -ClientId "c9534241-dde9-4d04-9d45-32b1fbff22ed" -ClientSecret "14c0c9af-2db1-48ab-b29c-51975df4afa2-739e4ef2-9aad-4fe9-b486-794feca48ea8" -Scopes "all" -Tenant "demo"
            This logs into Halo using the Client Credentials authorisation flow.
        .OUTPUTS
            Sets two script-scoped variables to hold connection and authentication information.
    #>
    [CmdletBinding(
        DefaultParameterSetName = 'Client Credentials'
    )]
    Param (
        # The URL of the Halo instance to connect to.
        [Parameter(
            ParameterSetName = 'Client Credentials',
            Mandatory = $True
        )]
        [URI]$URL,
        # The Client ID for the application configured in Halo.
        [Parameter(
            ParameterSetName = 'Client Credentials',
            Mandatory = $True
        )]
        [String]$ClientID,
        # The Client Secret for the application configured in Halo.
        [Parameter(
            ParameterSetName = 'Client Credentials',
            Mandatory = $True
        )]
        [String]$ClientSecret,
        # The API scopes to request, if this isn't passed the scope is assumed to be "all". Pass a string or array of strings. Limited by the scopes granted to the application in Halo.
        [Parameter(
            ParameterSetName = 'Client Credentials'
        )]
        [ValidateSet(
            "all",
            "admin",
            "read:tickets",
            "edit:tickets",
            "read:calendar",
            "edit:calendar",
            "read:customers",
            "edit:customers",
            "read:contracts",
            "edit:contracts",
            "read:suppliers",
            "edit:suppliers",
            "read:items",
            "edit:items",
            "read:projects",
            "edit:projects",
            "read:sales",
            "edit:sales",
            "read:quotes",
            "edit:quotes",
            "read:sos",
            "edit:sos",
            "read:pos",
            "edit:pos",
            "read:invoices",
            "edit:invoices",
            "read:reporting",
            "edit:reporting",
            "read:timesheets",
            "edit:timesheets",
            "read:software",
            "edit:software",
            "read:kb",
            "edit:kb",
            "read:assets",
            "edit:assets",
            "access:chat",
            "access:adpasswordreset"
        )]
        [String[]]$Scopes = "all",
        # The tenant name required for hosted Halo instances.
        [Parameter(
            ParameterSetName = 'Client Credentials'
        )]
        [String]$Tenant
    )
    # Convert scopes to space separated string if it's an array.
    if ($Scopes -is [system.array]) {
        $AuthScopes = $Scopes -Join " "
    } else {
        $AuthScopes = $Scopes
    }
    # Build a script-scoped variable to hold the connection information.
    $ConnectionInformation = @{
        URL = $URL
        ClientID = $ClientID
        ClientSecret = $ClientSecret
        AuthScopes = $AuthScopes
        Tenant = $Tenant
    }
    Set-Variable -Name "HAPIConnectionInformation" -Value $ConnectionInformation -Visibility Private -Scope Script -Force
    Write-Debug "Connection information set to: $($Script:HAPIConnectionInformation | Out-String)"
    # Halo authorisation request body.
    $AuthReqBody = @{
        grant_type = "client_credentials"
        client_id = $Script:HAPIConnectionInformation.ClientID
        client_secret = $Script:HAPIConnectionInformation.ClientSecret
        scope = $Script:HAPIConnectionInformation.AuthScopes
    }
    # Build the authentication URL.
    if ($Tenant) {
        $AuthURL = "$($URL)auth/token?tenant=$($Tenant)"
    } else {
        $AuthURL = "$($URL)auth/token"
    }
    # Build the WebRequest parameters.
    $WebRequestParams = @{
        Uri = $AuthURL
        Method = "POST"
        Body = $AuthReqBody
        ContentType = "application/x-www-form-urlencoded" 
    }
    try {
        $AuthReponse = Invoke-WebRequest @WebRequestParams
        $TokenPayload = ConvertFrom-Json -InputObject $AuthReponse.Content
        # Build a script-scoped variable to hold the authentication information.
        $AuthToken = @{
            Type = $TokenPayload.token_type
            Access = $TokenPayload.access_token
            Expires = Get-TokenExpiry -ExpiresIn $TokenPayload.expires_in
            Refresh = $TokenPayload.refresh_token
            Id = $TokenPayload.id_token
        }
        Set-Variable -Name "HAPIAuthToken" -Value $AuthToken -Visibility Private -Scope Script -Force
        Write-Verbose "Got authentication token."
        Write-Debug "Authentication token set to: $($Script:HAPIAuthToken | Out-String -Width 2048)"
    } catch {
        $ExceptionResponse = $_.Exception.Response
        Write-Error "The Halo API request `($($ExceptionResponse.RequestMessage.Method) $($ExceptionResponse.RequestMessage.RequestUri)`) responded with $($ExceptionResponse.StatusCode.Value__): $($ExceptionResponse.ReasonPhrase). You'll see more detail if using '-Verbose'"
        Write-Verbose $_
    }
}