Authentication overview

ApicAgent provides secure mechanisms for authenticating requests when monitoring external API endpoints. Proper authentication ensures that ApicAgent's monitoring agents can access protected resources while adhering to the security policies of the APIs being observed. The platform is designed to handle various authentication schemes, allowing developers to configure monitors for endpoints that require credentials to operate.

Authentication in ApicAgent focuses on outgoing requests initiated by the monitoring service to the specified API endpoint. This differs from authenticating into the ApicAgent platform itself, which uses standard user account credentials. The primary goal is to enable ApicAgent to mimic legitimate client interactions with an API, verifying its availability, performance, and correct behavior under authenticated conditions. ApicAgent encrypts all stored credentials to maintain data security and comply with standards such as GDPR ApicAgent security and compliance documentation.

Supported authentication methods

ApicAgent supports several common authentication methods, enabling integration with a wide range of APIs. The choice of method typically depends on the target API's security requirements and the level of access control it enforces. Each method has distinct characteristics regarding credential handling and security implications.

Method Description When to Use Security Level
API Key A unique, secret token passed in a header or query parameter to identify the client application. For APIs secured with simple token-based access, often used for identifying applications rather than individual users. Moderate (security depends on key secrecy; susceptible to interception if not transmitted over HTTPS).
Basic Authentication Sends a username and password, base64-encoded, in the Authorization HTTP header. For APIs requiring traditional username/password access, typically over HTTPS to prevent credential interception. Moderate (requires HTTPS; credentials are not encrypted, only encoded).
OAuth 2.0 An authorization framework that allows third-party applications to obtain limited access to an HTTP service, either on behalf of a resource owner or by orchestrating an API interaction. ApicAgent supports various OAuth 2.0 flows, such as Client Credentials. For APIs requiring delegated authorization, allowing ApicAgent to access resources without directly handling user credentials. Generally preferred for robust and secure API integrations. High (token-based, scope-limited access, often short-lived tokens and refresh mechanisms). More details on OAuth 2.0 are available from OAuth.net's official site.

Getting your credentials

The process of obtaining credentials for ApicAgent's authentication configurations depends entirely on the API you intend to monitor. ApicAgent itself does not issue these credentials; it consumes those generated by the API provider.

  • For API Keys: Typically, API keys are generated within the developer dashboard or account settings section of the API provider. For example, a service like Stripe allows users to generate Stripe API keys for different environments (test and live).
  • For Basic Authentication: These credentials usually correspond to a user account or a service account created within the target API's system. You would use the username and password associated with that account.
  • For OAuth 2.0: Obtaining OAuth 2.0 credentials often involves registering ApicAgent as a client application with the API provider. This process typically yields a client ID and a client secret. For example, Google provides a detailed guide on how to set up OAuth 2.0 credentials for Google APIs. Depending on the OAuth flow, you might also need to configure redirect URIs or obtain authorization codes. ApicAgent's configuration interface will guide you through entering these specific values.

Once you have the necessary credentials from your API provider, you will input them into the ApicAgent web interface when setting up or modifying an API monitor. This involves navigating to the specific monitor's configuration, selecting the desired authentication method, and populating the respective fields (e.g., API key, username/password, client ID/secret, token endpoint).

Authenticated request example

When configuring an API monitor in ApicAgent, the platform handles the construction of the HTTP request, including the authentication headers or parameters, based on your input. Here's a conceptual representation of how ApicAgent translates your configuration into an authenticated request:

API Key Authentication (Header)

If you configure an API Key to be sent in an X-API-Key header:

GET /api/v1/data
Host: example.com
X-API-Key: YOUR_API_KEY_HERE
User-Agent: ApicAgent/1.0

Basic Authentication

If you configure Basic Authentication with username and password:

GET /api/v1/users
Host: example.com
Authorization: Basic BASE64_ENCODED_USERNAME_PASSWORD
User-Agent: ApicAgent/1.0

Here, BASE64_ENCODED_USERNAME_PASSWORD would be the base64 encoding of username:password.

OAuth 2.0 Client Credentials Grant

For an OAuth 2.0 Client Credentials flow, ApicAgent would first make a request to the token endpoint to obtain an access token, then use that token in subsequent requests:

Step 1: Obtain Access Token

POST /oauth/token
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64_ENCODED_CLIENT_ID_SECRET

grant_type=client_credentials
scope=read

Response (example):

{
  "access_token": "YOUR_ACCESS_TOKEN_HERE",
  "token_type": "Bearer",
  "expires_in": 3600
}

Step 2: Make Authenticated API Request

GET /api/v1/protected-resource
Host: example.com
Authorization: Bearer YOUR_ACCESS_TOKEN_HERE
User-Agent: ApicAgent/1.0

ApicAgent manages the token acquisition and refresh process internally for supported OAuth 2.0 flows, simplifying the configuration for the user.

Security best practices

When configuring authentication for your API monitors in ApicAgent, adhering to security best practices is crucial to protect your credentials and the integrity of your API interactions.

  • Use HTTPS Everywhere: Always ensure that the API endpoints you are monitoring use HTTPS. This encrypts the communication channel, protecting sensitive credentials (like API keys or Basic Auth headers) from interception during transit. ApicAgent will typically warn or fail if attempting to monitor HTTP-only endpoints with authentication. The IETF's RFC 7230 on HTTP message syntax strongly recommends using TLS for all sensitive traffic.
  • Least Privilege Principle: Grant only the minimum necessary permissions to the credentials ApicAgent uses. If an API key only needs read access to a specific endpoint, configure it with only those permissions on the API provider's side. Avoid using administrator-level keys for monitoring tasks.
  • Dedicated Credentials: Create specific API keys or service accounts solely for ApicAgent's monitoring activities. This allows for easier revocation and auditing, distinguishing monitoring traffic from other application traffic.
  • Rotate Credentials Regularly: Periodically rotate your API keys, Basic Auth passwords, or OAuth client secrets. This reduces the window of opportunity for attackers if a credential is ever compromised. The frequency of rotation should align with your organization's security policies.
  • Monitor Credential Usage: Leverage logging and auditing features provided by your API gateway or API provider to track when and where your ApicAgent-specific credentials are being used. Unusual patterns could indicate a compromise.
  • Secure Credential Storage (ApicAgent): ApicAgent stores your configured credentials in an encrypted format within its infrastructure. While ApicAgent handles this internally, users should ensure their own local systems where they access ApicAgent's interface are also secure to prevent unauthorized access to the configuration settings.
  • Avoid Hardcoding Credentials: Never hardcode sensitive API credentials directly into codebases outside of ApicAgent's secure configuration. ApicAgent provides the secure mechanism for storing and using them.
  • Leverage OAuth 2.0 Where Possible: For APIs that support it, OAuth 2.0 offers a more secure and flexible authorization mechanism compared to simple API keys or Basic Auth, particularly due to its token-based, scope-limited, and often time-limited nature.