Skip to main content

​
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: 
# 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:
Cloud ValueHostnameDescription
us-1https://api.crowdstrike.comUS Commercial 1 (default)
us-2https://api.us-2.crowdstrike.comUS Commercial 2
eu-1https://api.eu-1.crowdstrike.comEuropean Union
us-gov-1https://api.laggar.gcw.crowdstrike.comUS GovCloud 1
us-gov-2https://api.us-gov-2.crowdstrike.milUS 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.
  • 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

Build docs developers (and LLMs) love

Get started for freeTalk to us