Skip to main content
🔐 OAuth 2.0 Setup

ServiceNow OAuth Setup

Connect Snow-Flow to your ServiceNow instance using OAuth 2.0. This guide walks you through creating an OAuth application and authenticating securely.

Prerequisites

✓

ServiceNow Instance

Access to a ServiceNow instance with admin rights

✓

Snow-Flow Installed

Snow-Flow CLI installed via npm

✓

OAuth Plugin Active

System OAuth plugin enabled in ServiceNow

1

Create OAuth Application in ServiceNow

  1. Navigate to System OAuth > Application Registry in your ServiceNow instance
  2. Click New and select "Create an OAuth API endpoint for external clients"
  3. Fill in the application details:
Field Value Notes
Name Snow-Flow MCP Descriptive name for the application
Client ID (auto-generated) Copy this value after saving
Client Secret (auto-generated) Copy this value after saving
Redirect URL http://localhost:3005/callback Required for OAuth flow
Active Checked
💡
Tip: The redirect URL must be exactly http://localhost:3005/callback. On local machines, Snow-Flow starts a temporary server on this port to receive the OAuth callback automatically. In remote environments (SSH, Codespaces, Docker), you will manually copy the callback URL from your browser instead.
2

Copy OAuth Credentials

  1. After saving the application, copy the following values:
Client ID abc123def456ghi789jkl012mno345pq
Client Secret xyz987wvu654tsr321qpo098nml765kj
Instance URL https://dev12345.service-now.com
⚠️
Security Note: Keep your Client Secret secure. Never commit it to version control or share it publicly.
3

Authenticate in Snow-Flow

Start Snow-Flow and use the /auth command:

Terminal 
# Start Snow-Flow
snow-flow

# In the TUI, type:
/auth

# Follow the prompts:
# 1. Enter your ServiceNow instance URL
# 2. Enter the Client ID
# 3. Enter the Client Secret
# 4. A browser window opens for OAuth consent
# 5. Authorize the application in ServiceNow
# 6. You'll be redirected back automatically
1
Enter credentials
→
2
Browser opens
→
3
Authorize in ServiceNow
→
✓
Connected!

Remote Environments

🖥️
In remote environments (GitHub Codespaces, SSH, Docker, Gitpod, WSL), Snow-Flow automatically detects the headless environment and shows an alternative auth flow. Instead of opening a browser, it displays a URL for you to copy.
Terminal 
# Same first 3 steps (instance, client ID, secret), then:
# 4. Snow-Flow shows an OAuth URL
# 5. Open the URL in your local browser
# 6. Authorize the application in ServiceNow
# 7. Your browser redirects to localhost (page may show an error)
# 8. Copy the FULL URL from your browser address bar
# 9. Paste the URL into Snow-Flow and press Enter
1
Enter credentials
→
2
Copy URL
→
3
Authorize
→
4
Paste callback URL
→
✓
Connected!
📁
Credentials stored at: ~/.local/share/snow-code/auth.json
4

Verify Connection

After authentication, verify the connection works:

Snow-Flow TUI 
# Check authentication status
/auth list

# Or ask the AI to query something
> Show me the latest 5 incidents

# If successful, you'll see real data from your instance!
🎉
Success! You're now connected to ServiceNow. All 379+ MCP tools are ready to use.

Alternative Configuration Methods

Environment Variables

Set credentials as environment variables for CI/CD or server deployments:

export SERVICENOW_INSTANCE_URL="https://dev12345.service-now.com"
export SERVICENOW_CLIENT_ID="your-client-id"
export SERVICENOW_CLIENT_SECRET="your-client-secret"

.env File

Store credentials in a .env file in your project directory:

# .env
SERVICENOW_INSTANCE_URL=https://dev12345.service-now.com
SERVICENOW_CLIENT_ID=your-client-id
SERVICENOW_CLIENT_SECRET=your-client-secret
⚠️
Add .env to .gitignore!

Direct Login Command

Pass the instance URL directly to the auth command:

snow-flow auth login https://dev12345.service-now.com

Troubleshooting

OAuth Error: Invalid Client

Double-check your Client ID and Client Secret. Make sure there are no extra spaces.

Redirect URI Mismatch

Ensure the Redirect URL in ServiceNow is exactly: http://localhost:3005/callback

Port 3005 Already in Use

Close other applications using port 3005, or check for stuck Snow-Flow processes.

Token Expired

Tokens are automatically refreshed. If issues persist, run /auth again to re-authenticate.

Remote/Headless Authentication

In GitHub Codespaces or SSH sessions, Snow-Flow shows a URL to copy instead of opening a browser. After authorizing, copy the full callback URL (including ?code=...) from your browser address bar and paste it back into Snow-Flow.

Ready to Build?

You're all set! Explore the MCP tools or learn more about the TUI.

Explore MCP Tools → TUI Guide