Documentation forServer & Application Monitor
Monitoring your applications and environment is a key capability of SolarWinds Observability Self-Hosted (formerly Hybrid Cloud Observability) and is available in the Essentials edition. Server & Application Monitor (SAM) is also available in a standalone module.

API poller authentication and authorization

Many REST APIs use some type of authorization and/or authentication mechanisms to check the validity of requests and to secure stored data.

  • Authentication proves the identity of a requestor. Many APIs require you to register as a user and include credentials in API requests. For example, to send requests to Azure APIs, you need to provide details such as Client ID and Tenant IDs to authenticate access.

    Authentication proves that you are who you say you are.

  • Authorization allows certain actions against data stored in the API. For example, you can use standard SolarWinds Platform account credentials to send GET requests that retrieve data from the SolarWinds Platform API, but if you send a POST request to change data with a CREATE, READ, UPDATE, or DELETE command, your SolarWinds Platform account requires extra rights. Adding a node requires Node Management rights.

    Authorization verifies that an authenticated request can perform certain actions.

Supported authorization types for SAM API pollers include:

  • No Authorization: No user names, passwords, or credentials are required for free, public APIs, also called open APIs. For example, iTunes Search is an open API (© 2020 Apple Inc., available at performance-partners.apple.com).

  • Basic Authorization: Also called "Basic Auth," this method passes the username and password in request headers, sent via HTTPS and encoded with Base64 for security. Passwords are required with Basic Authorization.

  • OAuth 2.0: Uses access tokens that the API server passes to an authentication server to grant access via public and private keys. Note the following details about OAuth 2.0:

  • Bearer Token: Also called token authentication, this scheme uses access tokens to authenticate requests, in the form of text strings added to request headers (for example, Authorization: Bearer <Your API Key>). Many tokens expire after a certain amount of time but some APIs offer "refresh tokens" with long lifespans. For example, SolarWinds DPA API tokens expire after 900 seconds but can be extended with an API_ACCESS_TOKEN_EXPIRATION option.

  • API Key: The API key is a long string included in either the request URL or request header (for example, Authorization: <Key> <Value>). Some APIs require both a public and private key -- the public key is usually included in the request, and the private key is treated like a password.

You can chain multiple API requests to save a value from one request for use in subsequent requests, including authorization and authentication data. This is useful for APIs that involve tokens, sessions, or endpoint discovery.

Review API documentation to determine what's required in requests. For example, requests sent to the SolarWinds Loggly API require an access token before a response is returned; the API uses the token to authenticate your identity. Additional tokens are then required to reach specific segments of data in subsequent requests; the API uses those details to verify what you can do to data.

The SolarWinds Pingdom API uses Bearer Token authorization so an API token must be included in each request, as shown in this example:

GET /checks HTTP/1.1
Host: api.pingdom.com
Authorization: Bearer ofOhK18Ca6w4S_2FEH5QnIbH0VZhRPO3tlvrjMIKQ36Vap

API credentials

Depending on the type of authorization used by an API, you may only need to provide basic credentials: a username and password. Some free APIs don't require any credentials. Sophisticated APIs, such as the Azure API, require a client ID, client secret, access token URL, and other details. Check API provider documentation for requirements.

Some terms you may encounter include:

  • Grant type: The method used by an application to get an access token that authenticates a request to an API endpoint.

  • Tenant ID: A unique ID that represents the Azure AD directory where a registered application is stored.

  • Client ID: A unique ID that is assigned to an application and service principal during initial provisioning.

  • Client Secret: A unique set of characters known only to the application and authorization server.

  • Access token URL: The web address of the API provider's authentication server, which exchange an authorization code for an access token.to confirm access to API data.

  • Scope: The endpoints of data within an API for which an application can request access. The access token issued to the application will be limited to the scopes granted, including read or write access permissions. For example, to monitor https://manage.office.com endpoints with the Microsoft 365 Admin Center API poller template, use the following scope: https://manage.office.com/.default.

    API pollers created from predefined templates often require a scope. For example, the Microsoft 365 Mobile Device Management API poller template requires OAuth 2.0 Azure credentials with the following scope:
    https://manage.office.com/.default. See the SAM API Poller Template Guide for details.

For tips on locating Azure credentials such as Tenant IDs, see Find Microsoft Azure credentials.

Configure credentials

To configure credentials for an API poller, you can either:

Credentials added on the API poller page are sent by HTTP with plain text, instead of HTTPS. Consider either adding credentials by logging in to the SolarWinds Platform server directly, or using the Manage Credentials page instead.

API permissions

In addition to credentials, many APIs limit access to data with API-specific permissions; review API documentation for details. For example, Azure uses role-based access control with a resource.operation.constraint pattern, as shown in these examples:

  • ServiceHealth.Read grants access to read service health information in the Office 365 Management API.
  • Reports.Read.All grants access to read usage reports in the Microsoft Graph API.

Work with your organization's Azure Administrator to configure Azure permissions. SolarWinds Technical Support cannot assist with permission-related issues related to third-party products, such as Azure, due to variations in customer environments and Program Limitations.

The following figure shows Reports.Read.All permissions configured in Azure for an API poller based on the Microsoft 365 Teams API poller template:

When configuring Azure permissions, use Application instead of Delegate as the Type for Microsoft Graph and Office 365 Management APIs. To learn more, see Use the portal to create an Azure AD application and service principal that can access resources. (Excerpts and screenshots in this section are attributed to © 2021 Microsoft Corp., available at docs.microsoft.com, .)