API poller authorization and authentication
Most APIs use some type of authorization to authenticating the sender of a request, and then verify that the sender has permission to access or manipulate relevant data. When creating an individual API poller or assigning an API poller template, you need to specify the type of authorization used by an API, and then add credentials, API tokens, or "secret keys", as necessary.
When working with REST APIs, note the difference between authentication and authorization:
- Authorization checks if an API request is allowed.
- Authentication checks the identity of a request, usually by validating credentials.
For example, requests sent to the SolarWinds Loggly API require an access token before a response is returned. Additional authentication tokens are then required to reach specific segments of data in subsequent requests. Linking multiple requests in a single API poller is referred to as "chaining" requests. For details, see Chain multiple API requests in a single API poller in SAM.
Most access tokens expire after a certain amount of time. For example, tokens for the SolarWinds DPA API expire after 900 seconds but you can extend that time with the API_ACCESS_TOKEN_EXPIRATION option. Some APIs offer refresh tokens with long lifespans.
The API Poller feature supports the following types of authorization. If credentials are required, you can select an existing set of credentials or enter them manually.
- No Authorization: No user names, passwords, or credentials are required. These APIs are sometimes called "free" or "open public" APIs. For example, iTunes Search is an open API (© 2020 Apple Inc., available at affiliate.itunes.apple.com, obtained on September 1, 2020).
- 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. SAM currently only supports the Client Credentials Grant Type. To use OAuth 2.0, provide:
- Client ID: The ID for your client application, as registered with the API provider.
- Client Secret: The client secret given to you by the API provider.
- Access Token URL: The provider's authentication server, to exchange an authorization code for an access token.
- Scope: The scope of access you're requesting, which may include multiple space-separated values.
- 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>).
- 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.
If a monitored API is available via an HTTP connection, credentials are not encrypted. They're sent in headers as plain text.
Review API documentation to determine what's required in requests. For example, 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_XmInGv0QPkqly-rbRBBoHsp_2FEH5QnIbH0VZhRPO3tlvrjMIKQ36Vap