The validate_api_key() method allows your MCP server to proactively check the status of a User API Key with AgentPay before attempting a consume() call or performing other actions.
The agentpay-sdk package currently on PyPI is a placeholder to reserve the name during Early Access. To get the actual SDK now, join the Waitlist.

​
Method Signature

validation_result = agentpay_client.validate_api_key(api_key="USER_API_KEY_HERE")

​
Parameters

  • api_key (str, required):
    • The User API Key that you want to validate.

​
Return Object (ValidationResult)

The validate_api_key() method returns a ValidationResult object with the following attributes:
  • is_valid (bool):
    • True if the API key is valid, active, and recognized by AgentPay for your service.
    • False otherwise (e.g., key does not exist, is inactive, suspended, or not associated with your service).
  • invalid_reason (str | None):
    • If is_valid is False, provides the reason for invalidity. Possible values:
      • "invalid_key": The key is not recognized or has been revoked
      • "outstanding_payment": The key is associated with an account that has outstanding payments
      • "insufficient_balance": The key is valid but the associated account has insufficient balance
    • None if is_valid is True

​
Example

# Assume agentpay_client is an initialized AgentPayClient instance
validation_result = agentpay_client.validate_api_key(api_key="user_api_key_here")

if validation_result.is_valid:
    # Key is valid, proceed with operation
    print("API Key is valid")
else:
    # Key is invalid, handle based on reason
    print(f"API Key is invalid: {validation_result.invalid_reason}")

​
Error Handling

The method may raise the following exceptions:
  • AgentPayError: If there is an error communicating with the AgentPay service
  • ValueError: If the api_key parameter is empty or None

​
Performance Considerations

  • The method makes a synchronous HTTP request to the AgentPay service
  • Typical response time is < 100ms
  • We may release an asynchronous version in the future as needed

​
When to Use validate_api_key()

  • Proactive Checks: Use it when you want to confirm key validity before a consume() call, perhaps for non-billable operations that still require a legitimate user, or to provide more granular feedback to the user about their key status.
  • Middleware: It can be integrated into request middleware to check keys early in the request lifecycle.
  • Avoid Redundancy: If an operation will always result in a consume() call, the consume() method itself will validate the key. Calling validate_api_key() and then immediately consume() for every billable action would be redundant; only if there is meaningful business logic in between.
If validate_api_key() indicates an invalid key, you should typically deny access to the protected resource or functionality.