Authentication

Learn how to authenticate with CrowdStrike Falcon APIs using PSFalcon’s OAuth2 implementation

Overview

PSFalcon uses OAuth2 authentication to securely connect to CrowdStrike Falcon APIs. Your credentials and access tokens are cached for automatic re-use, and tokens are automatically refreshed when they approach expiration.

Requesting an Access Token

Use Request-FalconToken to authenticate with the Falcon APIs:

Basic Authentication

# Authenticate with ClientId and ClientSecret
Request-FalconToken -ClientId 'abc123...' -ClientSecret 'xyz789...'

Cloud Regions

PSFalcon supports all CrowdStrike cloud regions. Use the -Cloud parameter for automatic hostname resolution:

Available Cloud Regions

Cloud Value	Hostname	Description
us-1	https://api.crowdstrike.com	US Commercial 1 (default)
us-2	https://api.us-2.crowdstrike.com	US Commercial 2
eu-1	https://api.eu-1.crowdstrike.com	European Union
us-gov-1	https://api.laggar.gcw.crowdstrike.com	US GovCloud 1
us-gov-2	https://api.us-gov-2.crowdstrike.mil	US GovCloud 2

If you don’t specify a cloud region, PSFalcon defaults to us-1. The module automatically follows redirects if you connect to the wrong region.

Authentication Parameters

The Request-FalconToken function accepts the following parameters from source code /home/daytona/workspace/source/public/oauth2.ps1:32-74:

1. ClientId (Required)

   Your OAuth2 client identifier. Must be a 32-character hexadecimal string matching pattern ^[a-fA-F0-9]{32}$.

   If not provided, you’ll be prompted to enter it interactively.

2. ClientSecret (Required)

   Your OAuth2 client secret. Must be a 40-character alphanumeric string matching pattern ^\w{40}$.

   If not provided, you’ll be prompted to enter it interactively.

3. Cloud (Optional)

   CrowdStrike cloud region: us-1, us-2, eu-1, us-gov-1, or us-gov-2.

   Defaults to us-1 if not specified.

4. MemberCid (Optional)

   Member customer identifier for Falcon Flight Control (multi-CID) environments. Must match pattern ^[a-fA-F0-9]{32}(-\w{2})?$.

   Used when authenticating as a parent CID to access a specific child CID.

Credential Caching

PSFalcon automatically caches your credentials and token in the $Script:Falcon variable:

# After successful authentication, these values are cached:
# - ClientId
# - ClientSecret  
# - MemberCid (if provided)
# - Hostname
# - Access token
# - Token expiration time

Cached credentials are stored in memory for the duration of your PowerShell session. They are not persisted to disk.

Automatic Token Refresh

From /home/daytona/workspace/source/public/oauth2.ps1:8-10 and oauth2.ps1:208:

• Access tokens are valid for a specific duration (typically 30 minutes)
• PSFalcon automatically checks token expiration before each API request
• If the token expires in less than 240 seconds (4 minutes), a new token is automatically requested
• You don’t need to manually refresh tokens

# Token refresh happens automatically during API calls
Get-FalconHost -Limit 10  # Token checked/refreshed if needed

Checking Token Status

Use Test-FalconToken to check your current authentication status:

Test-FalconToken

# Output:
# Token     : True
# Hostname  : https://api.crowdstrike.com
# ClientId  : abc123def456...
# MemberCid : 

The Token property indicates whether you have a valid, non-expired access token.

Viewing Your Token

Display the raw OAuth2 access token value:

Show-FalconToken
# Returns: Bearer token string

The access token is sensitive. Avoid logging or exposing it in scripts.

Revoking Tokens

Always revoke your token when you’re done to follow security best practices:

Complete Script Example

try {
    # Request token
    Request-FalconToken -ClientId $ClientId -ClientSecret $ClientSecret
    
    # Perform API operations
    Get-FalconHost -Limit 5
    
} finally {
    # Always revoke token
    if ((Test-FalconToken).Token -eq $true) {
        Revoke-FalconToken
    }
}

Revoke-FalconToken clears cached credentials and revokes the active token with the API.

Flight Control (Multi-CID)

When working with Falcon Flight Control, use the -MemberCid parameter to authenticate to specific child CIDs:

1. Authenticate to Parent CID

   Request-FalconToken -ClientId $ParentClientId -ClientSecret $ParentSecret
   
2. Switch to Child CID

   # Re-authenticate with MemberCid to access child CID
   Request-FalconToken -ClientId $ParentClientId -ClientSecret $ParentSecret -MemberCid $ChildCid
   
3. Work with Child Resources

   # All subsequent commands operate in the child CID context
   Get-FalconHost -Limit 10
   

Advanced: Custom URLs

For troubleshooting or testing, you can specify a custom API URL:

Request-FalconToken -ClientId $Id -ClientSecret $Secret -CustomUrl 'https://custom.api.url'

The -CustomUrl parameter is for module troubleshooting only. Use -Cloud or -Hostname for production scenarios.

Automatic Region Redirect

From /home/daytona/workspace/source/public/oauth2.ps1:181-193:

PSFalcon automatically detects and follows region redirects:

# Connect to wrong region
Request-FalconToken -ClientId $Id -ClientSecret $Secret -Cloud 'us-1'

# If your tenant is in 'us-2', PSFalcon automatically:
# 1. Detects the X-Cs-Region header from the response
# 2. Updates the cached Hostname to the correct region
# 3. Retries the token request

Error Handling

Handle authentication errors gracefully:

try {
    Request-FalconToken -ClientId $ClientId -ClientSecret $ClientSecret
    
    if ((Test-FalconToken).Token -ne $true) {
        throw "Authentication failed"
    }
    
} catch {
    Write-Error "Failed to authenticate: $_"
    exit 1
}

Best Practices

1. Store Credentials Securely

   Never hardcode credentials in scripts. Use environment variables, secure credential storage, or prompt for input:

   # Use environment variables
   $ClientId = $env:FALCON_CLIENT_ID
   $ClientSecret = $env:FALCON_CLIENT_SECRET
   
   # Or use Get-Credential for interactive scripts
   $Cred = Get-Credential -Message "Enter Falcon API credentials"
   
2. Always Revoke Tokens

   Use try/finally blocks to ensure tokens are revoked:

   try {
       Request-FalconToken -ClientId $Id -ClientSecret $Secret
       # Your code here
   } finally {
       if ((Test-FalconToken).Token) { Revoke-FalconToken }
   }
   
3. Verify Authentication

   Always check token status after requesting it:

   Request-FalconToken -ClientId $Id -ClientSecret $Secret
   
   if ((Test-FalconToken).Token -ne $true) {
       throw "Authentication failed"
   }
   
4. Use Appropriate Scopes

   Create API clients with the minimum required scopes for your use case in the Falcon console.

Related Commands

• Request-FalconToken - Request an OAuth2 access token
• Test-FalconToken - Check token status
• Show-FalconToken - Display token value
• Revoke-FalconToken - Revoke and clear cached credentials

Next Steps

Error Handling

Learn how PSFalcon handles API errors and response validation

Pagination

Understand automatic pagination for large result sets