> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentpay.me/llms.txt
> Use this file to discover all available pages before exploring further.

# .validate_api_key() Method

> Reference for the AgentPayClient.validate_api_key() method, for proactively checking the status and validity of a User API Key.

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.

<Note>
  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](https://agentpay.me).
</Note>

## Method Signature

```python theme={null}
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

```python theme={null}
# 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.