Your ServiceNow instance needs to call external APIs that require authentication, and hardcoding credentials in scripts is a security nightmare waiting to happen. This guide shows you how to set up proper authentication profiles and REST Messages that keep credentials secure and maintainable.
Why REST Message authentication matters
Before REST Messages with authentication profiles, developers were embedding API keys and passwords directly in Script Includes and Business Rules. Every credential change meant hunting through code, and security audits were a mess because secrets were scattered across scripts. Platform architects inherited instances where production API keys were visible in plain text to anyone with script access. The stakeholders here are integration developers who build the connections, security teams who audit credential management, and platform admins who maintain these integrations when APIs change or credentials rotate.
How ServiceNow REST authentication works
ServiceNow separates the 'what' from the 'how' — REST Messages define the endpoint and parameters, while Authentication Profiles handle the credentials and auth flow. You start with a basic REST Message pointing to your endpoint, then attach an auth profile that matches what the external API expects: Basic Auth for simple username/password, OAuth 2.0 for token-based flows, or API key headers for services that use bearer tokens or custom headers. The REST Message references the auth profile by sys_id, so ServiceNow handles credential injection automatically when you call the service.
Production-quality REST integrations
Once basic authentication works, production improvements focus on resilience and maintainability. Add proper error handling for auth failures, implement token refresh logic for OAuth flows that expire, and set up monitoring so you know when external APIs change their auth requirements. Consider creating separate auth profiles for dev, test, and prod environments with the same name but different credentials — your scripts stay environment-agnostic while credentials stay segregated. Well-designed REST integrations fail gracefully when auth goes wrong and log enough detail for troubleshooting without exposing sensitive data.
Before you start
- •rest_service_admin or admin role
- •External API credentials and authentication requirements documented
- •Network access to external API endpoint from ServiceNow instance
Sourdough: ServiceNow Monitoring and Analytics
A Chrome extension for ServiceNow Admins and Developers with essential tools, analytics, graphs and monitoring features.
Free to install. Pro $5/month after a 14-day no-card trial.
Pro requires the ServiceNow admin role. Upgrade inside the extension.
Step by step
Create the authentication profile
Navigate to System Web Services > Outbound > Authentication Profile and click New. Select the Type that matches your external API: Basic for username/password, OAuth 2.0 for token flows, or API Key for header-based auth. Fill in the Name field with something descriptive like 'Salesforce OAuth' or 'GitHub API Key' — you'll reference this in scripts later.
Use consistent naming conventions across auth profiles so developers can predict the profile name when writing integrations.
Configure authentication credentials
For Basic Auth, enter the Username and Password fields directly. For OAuth 2.0, provide the Client ID, Client Secret, Token URL, and any required Scope values from your external API documentation. For API Key, set the Header Name (like 'Authorization' or 'X-API-Key') and Header Value (the actual key). Click Submit to save the profile.
Create the REST Message
Go to System Web Services > Outbound > REST Message and click New. Set the Name to something that identifies the external service, like 'Salesforce REST API' or 'GitHub Integration'. In the Endpoint field, enter the base URL of the external API. Leave Authentication Type as 'Inherit from authentication profile' — this is crucial for security.
Link the authentication profile
In the Authentication Profile field, select the profile you created in step 1. ServiceNow will use this profile's credentials for all HTTP methods in this REST Message. The Endpoint Preview section will show how the final request will look, including auth headers, but won't expose sensitive values.
Create HTTP methods
Scroll to the HTTP Methods related list and click New. Set the HTTP Method (GET, POST, PUT, DELETE) and add any path segments in the Endpoint field — this gets appended to the base endpoint from the REST Message. Configure Headers for content type or custom API requirements. Each method inherits authentication from the parent REST Message automatically.
Test the authentication
On your HTTP Method record, click the Test link. ServiceNow will make a real request to the external API using your authentication profile. Check the Response tab for successful auth (usually 200 status) or auth errors (401/403 status). The Request tab shows exactly what ServiceNow sent, minus sensitive auth details.
Test with a simple GET request first — if auth works for GET, it'll work for other methods using the same profile.
Use in server-side scripts
In Business Rules or Script Includes, instantiate the REST Message with 'var rm = new sn_ws.RESTMessageV2("Your REST Message Name", "HTTP Method Name")'. Call rm.execute() to send the request. ServiceNow automatically includes authentication based on the linked profile. Never override authentication in scripts — let the profile handle it.
Handle authentication errors
Check the response status with response.getStatusCode() and handle 401/403 errors explicitly. For OAuth flows, these usually mean token expiration — log the error for monitoring but don't expose credential details in error messages. Use response.getErrorMessage() for debugging, but sanitize before logging.
Best practices
Never store credentials in Script Includes or Business Rules — always use Authentication Profiles so credentials stay encrypted in sys_auth_profile.
Create separate auth profiles for each environment (dev/test/prod) with identical names but different credentials to keep scripts environment-agnostic.
For OAuth 2.0, set up token refresh handling in your scripts because ServiceNow doesn't automatically refresh expired tokens.
Use descriptive REST Message names that match the external service because you'll reference these by name in scripts.
Test auth profiles immediately after creation — external APIs change authentication requirements without notice, and early testing catches configuration problems.
Test Your Knowledge
Quick 3-question quiz — see how your ServiceNow skills stack up.
A list view on a table with millions of records is slow. Best fix?
Select an answer to continue