Skip to main content

​
Overview

PSFalcon uses OAuth2 client credentials for authentication. These cmdlets manage the token lifecycle and credential caching for seamless API access.
All API operations require a valid OAuth2 access token. Use Request-FalconToken before making any API calls.

​
Request-FalconToken

Request an OAuth2 access token using your API credentials. 
Request-FalconToken -ClientId <string> -ClientSecret <string>

​
Parameters

​
ClientId
string
OAuth2 client identifier (32-character hexadecimal)Pattern: ^[a-fA-F0-9]{32}$Aliases: client_idIf not provided, you will be prompted to enter it interactively.
​
ClientSecret
string
OAuth2 client secret (40-character alphanumeric)Pattern: ^\w{40}$Aliases: client_secretIf not provided, you will be prompted to enter it interactively.
​
Cloud
string
CrowdStrike cloud regionValid values:
  • us-1 - US Commercial 1 (default)
  • us-2 - US Commercial 2
  • eu-1 - EU Cloud
  • us-gov-1 - US GovCloud 1
  • us-gov-2 - US GovCloud 2
This parameter simplifies hostname selection. Automatically converts to the appropriate Hostname value.
​
Hostname
string
CrowdStrike API hostname (alternative to Cloud parameter)Valid values:
  • https://api.crowdstrike.com (us-1)
  • https://api.us-2.crowdstrike.com (us-2)
  • https://api.eu-1.crowdstrike.com (eu-1)
  • https://api.laggar.gcw.crowdstrike.com (us-gov-1)
  • https://api.us-gov-2.crowdstrike.mil (us-gov-2)
Use Cloud parameter for simpler syntax unless you need direct hostname control.
​
CustomUrl
string
Custom API URL for module troubleshootingUsed for testing or custom deployments. Overrides the Hostname parameter.
​
MemberCid
string
Member CID for multi-CID authentication (Falcon Flight Control)Pattern: ^[a-fA-F0-9]{32}(-\w{2})?$Aliases: cid, member_cidUsed when authenticating from a parent CID to access a child CID’s resources.
​
Collector
hashtable
Event collector configuration for logging token requestsRequired keys:
  • Uri - LogScale/Humio ingest endpoint
  • Token - Ingest token
Optional keys:
  • Enable - Enable event collection (boolean)
Integrates with Register-FalconEventCollector for audit logging.

​
Behavior

Credential Caching:
  • Stores ClientId, ClientSecret, Hostname, and MemberCid for re-use
  • Caches the OAuth2 access token with expiration timestamp
  • Automatically requests a new token when current token expires in < 240 seconds
Cloud Redirection:
  • Automatically follows redirects to the correct cloud region
  • Updates cached hostname if redirected (indicated by X-Cs-Region header)
TLS Configuration:
  • Automatically sets TLS 1.2 for secure communication
  • Supports both [System.Net.Http.HttpClientHandler] and [Net.ServicePointManager]

​
Examples

# Initial authentication with credentials
Request-FalconToken -ClientId 'a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6' -ClientSecret 'Abc123Def456Ghi789Jkl012Mno345Pqr678Stu9'

​
Revoke-FalconToken

Revoke your active OAuth2 access token and clear cached credentials. 
Revoke-FalconToken

​
Description

Revokes the current OAuth2 access token at the CrowdStrike API and clears all cached credential information from the module, including:
  • OAuth2 access token
  • ClientId
  • ClientSecret
  • MemberCid
After revocation, you must call Request-FalconToken again to authenticate.

​
Parameters

This cmdlet has no parameters.

​
Examples

# Revoke token and clear credentials
Revoke-FalconToken

# Requires new authentication
Request-FalconToken -ClientId $NewClientId -ClientSecret $NewClientSecret

​
Show-FalconToken

Display your current OAuth2 access token value. 
Show-FalconToken

​
Description

Returns the current OAuth2 access token string (without the Bearer prefix). Useful for debugging or using the token outside PSFalcon.
Access tokens are sensitive credentials. Do not share or log them in unsecured locations.

​
Parameters

This cmdlet has no parameters.

​
Output

Returns the access token as a string, or throws an error if no token is available.

​
Examples

# Show current token value
Show-FalconToken
# Output: eyJhbGciOiJSUzI1NiIsImtpZCI6InB1YmxpYzo...

​
Test-FalconToken

Display OAuth2 access token status and cached credential information. 
Test-FalconToken

​
Description

Returns a [PSCustomObject] containing token status and cached credential information without exposing sensitive values.

​
Parameters

This cmdlet has no parameters.

​
Output

Returns an object with the following properties:
​
Token
boolean
$true if a valid token exists and expires in > 240 seconds, otherwise $false
​
Hostname
string
Cached CrowdStrike API hostname
​
ClientId
string
Cached OAuth2 client identifier
​
MemberCid
string
Cached member CID (if applicable)

​
Examples

# Check if authenticated
$Status = Test-FalconToken
if ($Status.Token) {
    Write-Host "Authenticated to: $($Status.Hostname)"
} else {
    Write-Host "Not authenticated or token expired"
    Request-FalconToken
}

​
Authentication Workflow

1

Request Token

Authenticate with Request-FalconToken using your API credentials
Request-FalconToken -ClientId $ClientId -ClientSecret $ClientSecret
2

Automatic Token Refresh

PSFalcon automatically refreshes your token when it expires in < 240 secondsNo action required - happens transparently during API calls
3

Check Status (Optional)

Verify authentication status at any time
Test-FalconToken
4

Revoke When Done

Revoke token when finished (optional but recommended)
Revoke-FalconToken

​
Best Practices

Never hardcode credentials in scripts. Use secure storage methods:
# Store credentials securely
$ClientId = 'your-client-id'
$ClientSecret = Get-Content 'C:\secure\secret.txt' | ConvertTo-SecureString
$SecretPlain = [System.Runtime.InteropServices.Marshal]::PtrToStringAuto(
    [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($ClientSecret)
)
Request-FalconToken -ClientId $ClientId -ClientSecret $SecretPlain
Or use environment variables:
Request-FalconToken -ClientId $env:FALCON_CLIENT_ID -ClientSecret $env:FALCON_CLIENT_SECRET
  • Tokens are valid for 30 minutes by default
  • PSFalcon auto-refreshes tokens expiring in < 4 minutes
  • Revoke tokens when switching contexts or ending sessions
  • Use Test-FalconToken to verify authentication state
In Falcon Flight Control (multi-CID) environments:
# Authenticate to parent CID first
Request-FalconToken -ClientId $ParentClientId -ClientSecret $ParentClientSecret

# Switch to child CID
Request-FalconToken -MemberCid $ChildCid

# Perform operations in child context
Get-FalconHost -Limit 5

# Switch back to parent or another child
Request-FalconToken  # Back to parent
Request-FalconToken -MemberCid $AnotherChildCid  # Different child
Always handle authentication errors gracefully:
try {
    Request-FalconToken -ClientId $ClientId -ClientSecret $ClientSecret
    Write-Host "Authentication successful"
} catch {
    Write-Error "Authentication failed: $($_.Exception.Message)"
    # Check credentials, cloud region, network connectivity
    exit 1
}

​
Troubleshooting

Error: Cannot validate argument on parameter "ClientId"Solution: Ensure ClientId is exactly 32 hexadecimal characters and ClientSecret is exactly 40 alphanumeric characters.
Symptom: HTTP 308 redirects or connection failuresSolution: Verify you’re using the correct Cloud parameter for your API credentials:
  • US Commercial customers: us-1 or us-2
  • EU customers: eu-1
  • GovCloud customers: us-gov-1 or us-gov-2
Error: No access token availableSolution: Run Request-FalconToken again. If credentials are cached, no parameters are needed.
Error: Cannot validate argument on parameter "MemberCid"Solution: Verify MemberCid format matches ^[a-fA-F0-9]{32}(-\w{2})?$

CrowdStrike API Documentation

Official API documentation and OAuth2 reference

PSFalcon Wiki

Community examples and detailed guides

Build docs developers (and LLMs) love

Get started for freeTalk to us