Authentication overview
Audexum employs robust authentication mechanisms to ensure that all interactions with its APIs are authorized and secure. Authentication is the process of verifying a client's identity, establishing trust, and determining whether the client is permitted to access specific resources or perform certain actions. Audexum's authentication protocols are designed to protect sensitive data and maintain the integrity of operations, aligning with industry best practices for API security.
The choice of authentication method depends on the specific use case, the type of client application, and the level of access required. For server-to-server communication where a client application directly accesses its own resources, API keys or the OAuth 2.0 Client Credentials flow are typically used. When a third-party application needs to access user-specific data with the user's explicit permission, the OAuth 2.0 Authorization Code flow is the standard approach. Audexum's API Security documentation provides a comprehensive guide to these principles.
All authenticated requests to Audexum APIs must be made over HTTPS to encrypt data in transit, protecting credentials and sensitive information from interception. Failure to use HTTPS will result in connection rejection or authentication errors.
Supported authentication methods
Audexum supports key authentication methods to accommodate a variety of integration scenarios:
- API Keys: A simple, token-based authentication method suitable for server-to-server communication or when an application needs to access its own data. API keys are long, randomly generated strings that identify the calling application.
- OAuth 2.0: An industry-standard protocol for authorization that allows a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. Audexum supports specific OAuth 2.0 grant types. The OAuth 2.0 specification outlines the various grant types and their uses.
API Keys
API keys provide a straightforward way to authenticate requests, primarily for applications that manage their own data or interact with Audexum as a service. These keys are unique to your Audexum account and should be treated as sensitive credentials. They are typically passed in the Authorization header of HTTP requests.
OAuth 2.0
Audexum implements OAuth 2.0 to facilitate secure delegated access. This is particularly important for applications that need to access user-specific data without ever handling the user's credentials directly. Audexum supports the following OAuth 2.0 grant types:
- Client Credentials Grant: Used when the client is requesting access to protected resources under its own control, or to protected resources previously arranged with the authorization server. This flow is suitable for server-to-server applications where no user interaction is involved. The client authenticates directly with Audexum using its client ID and client secret to obtain an access token.
- Authorization Code Grant: The most common and recommended flow for confidential clients (like web applications) that can securely maintain a client secret. This flow involves redirecting the user's browser to Audexum's authorization server for consent, then exchanging an authorization code for an access token. This flow ensures the user's credentials are never exposed to the client application.
The following table summarizes Audexum's supported authentication methods:
| Method | When to Use | Security Level |
|---|---|---|
| API Key | Server-to-server, accessing application's own data | Medium (requires secure storage and transmission) |
| OAuth 2.0 Client Credentials | Server-to-server, machine-to-machine, accessing application's own resources | High (short-lived tokens, client secret required) |
| OAuth 2.0 Authorization Code | Web applications, mobile applications accessing user-specific data | Very High (delegated access, user consent, no credential sharing) |
Getting your credentials
To interact with Audexum APIs, you must first obtain the necessary authentication credentials. The process typically begins in the Audexum Developer Portal.
For API Keys
- Log in to your Audexum Developer Portal account.
- Navigate to the "API Keys" section, usually found under "Settings" or "Security."
- Generate a new API key. You may be prompted to provide a name or description for the key to help with organization.
- The generated key will be displayed once. Copy it immediately as it may not be retrievable later for security reasons. Store this key securely.
Refer to Audexum's API Key Management guide for detailed instructions specific to your account.
For OAuth 2.0 Clients
To use OAuth 2.0, you need to register your application with Audexum to obtain a Client ID and Client Secret.
- Log in to the Audexum Developer Portal.
- Go to the "Applications" or "OAuth Clients" section.
- Register a new application, providing details such as:
- Application Name: A descriptive name for your application.
- Redirect URI(s): For Authorization Code flow, these are the URLs where Audexum will redirect the user after they grant or deny access. These must be exact matches to prevent redirection attacks. You can specify multiple redirect URIs.
- Application Type: (e.g., Web, Mobile, Server-to-Server).
- Upon successful registration, Audexum will issue a Client ID and a Client Secret. The Client Secret is highly sensitive and should be stored securely, similar to an API key.
For more information on setting up OAuth 2.0 applications, consult the Audexum OAuth 2.0 Setup documentation.
Authenticated request example
This section provides examples of how to include authentication credentials in your API requests to Audexum. All examples assume you are making requests to api.audexum.com.
Using an API Key
API keys are typically passed in the Authorization header as a Bearer token. Replace YOUR_API_KEY with your actual key.
curl -X GET \
'https://api.audexum.com/v1/data' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json'
import requests
api_key = "YOUR_API_KEY"
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
response = requests.get("https://api.audexum.com/v1/data", headers=headers)
print(response.json())
Using OAuth 2.0 Access Token (Client Credentials Grant)
First, obtain an access token using your Client ID and Client Secret. Then, use this access token in subsequent API calls.
Step 1: Get Access Token
curl -X POST \
'https://auth.audexum.com/oauth/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET'
The response will contain an access_token and its expires_in duration.
{
"access_token": "eyJraWQiOiJmZ...",
"token_type": "Bearer",
"expires_in": 3600
}
Step 2: Use Access Token in API Call
Replace YOUR_ACCESS_TOKEN with the token obtained in Step 1.
curl -X GET \
'https://api.audexum.com/v1/user/profile' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json'
Security best practices
Implementing strong authentication is critical, but maintaining security also requires adhering to best practices:
- Keep Credentials Confidential: Never hardcode API keys or client secrets directly into your application's source code, especially for client-side applications. Store them in environment variables, secure configuration files, or a secrets management service (e.g., AWS Secrets Manager, Google Secret Manager, Azure Key Vault). The AWS Secrets Manager documentation provides guidance on securely storing and retrieving credentials.
- Use HTTPS/TLS Always: All communication with Audexum APIs must use HTTPS (TLS). This encrypts data in transit, protecting your credentials and sensitive payload data from eavesdropping. Audexum enforces HTTPS for all API endpoints.
- Rotate Credentials Regularly: Periodically rotate your API keys and client secrets. This reduces the window of opportunity for an attacker if a credential is compromised. Audexum recommends rotating keys at least every 90 days. Check the Audexum Credential Rotation policy for specific recommendations.
- Implement Least Privilege: Configure your API keys or OAuth clients with the minimum necessary permissions required for your application to function. Avoid granting broad access unless absolutely necessary. Audexum's Scopes and Permissions guide details how to configure granular access.
- Validate Redirect URIs (OAuth 2.0): For OAuth 2.0 Authorization Code flow, ensure that the redirect URIs registered in the Audexum Developer Portal are as specific as possible and fully match the URIs used by your application. This prevents malicious clients from intercepting authorization codes. Developers can learn more about this from the Google OAuth 2.0 Web Server Applications guide.
- Handle Access Tokens Securely: OAuth 2.0 access tokens have a limited lifetime. Store them in memory for the duration of their validity, and refresh them using a refresh token (if applicable to your flow and Audexum's implementation) when they expire. Avoid storing access tokens in persistent storage like databases or local storage unnecessarily.
- Monitor API Usage: Regularly review API access logs for unusual activity, failed authentication attempts, or excessive requests. This can help detect and respond to potential security incidents early. Audexum provides API monitoring tools within its Developer Portal.
- Error Handling: Implement robust error handling for authentication failures. Avoid providing overly descriptive error messages that could reveal sensitive information about your system to potential attackers. Generic messages like "Authentication failed" are preferred.