# Agent authentication

> Agent authentication - Learn how to implement authentication in DataRobot Agent Templates, covering
> API tokens, authorization context, OAuth 2.0, and security best practices.

This Markdown file sits beside the HTML page at the same path (with a `.md` suffix). It summarizes the topic and lists links for tools and LLM context.

Companion generated at `2026-04-24T16:03:56.222496+00:00` (UTC).

## Primary page

- [Agent authentication](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-authentication.html): Full documentation for this topic (HTML).

## Sections on this page

- [Authentication methods](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-authentication.html#authentication-methods): In-page section heading.
- [API token authentication](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-authentication.html#api-token-authentication): In-page section heading.
- [DataRobot API authentication](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-authentication.html#datarobot-api-authentication): In-page section heading.
- [External API authentication](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-authentication.html#external-api-authentication): In-page section heading.
- [MCP server authentication](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-authentication.html#mcp-server-authentication): In-page section heading.
- [Authorization context](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-authentication.html#authorization-context): In-page section heading.
- [OAuth 2.0 authentication](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-authentication.html#oauth-2-0-authentication): In-page section heading.
- [Security best practices](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-authentication.html#security-best-practices): In-page section heading.
- [Troubleshooting authentication issues](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-authentication.html#troubleshooting-authentication-issues): In-page section heading.
- [Common issues](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-authentication.html#common-issues): In-page section heading.
- [Missing API token](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-authentication.html#missing-api-token): In-page section heading.
- [Invalid endpoint](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-authentication.html#invalid-endpoint): In-page section heading.
- [Authorization context not set](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-authentication.html#authorization-context-not-set): In-page section heading.
- [OAuth token expired](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-authentication.html#oauth-token-expired): In-page section heading.
- [MCP server authentication failure](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-authentication.html#mcp-server-authentication-failure): In-page section heading.
- [Debugging tips](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-authentication.html#debugging-tips): In-page section heading.
- [Enable verbose logging](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-authentication.html#enable-verbose-logging): In-page section heading.
- [Check environment variables](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-authentication.html#check-environment-variables): In-page section heading.
- [Test authentication](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-authentication.html#test-authentication): In-page section heading.
- [Validate authorization context](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-authentication.html#validate-authorization-context): In-page section heading.

## Related documentation

- [Agentic AI](https://docs.datarobot.com/en/docs/agentic-ai/index.html): Linked from this page.
- [Build](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/index.html): Linked from this page.
- [API keys and tools section of your account settings](https://docs.datarobot.com/en/docs/platform/acct-settings/api-key-mgmt.html): Linked from this page.
- [tool integration documentation](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-tools-integrate.html): Linked from this page.
- [MCP tools documentation](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html): Linked from this page.
- [runtime parameters documentation](https://docs.datarobot.com/en/docs/api/code-first-tools/drum/custom-model-runtime-parameters.html): Linked from this page.

## Documentation content

# Agent authentication

AI agents often need to authenticate to external resources to complete tasks. For example, a deployed agent might need to access external APIs, databases, or cloud services to retrieve data or perform operations.

This documentation provides comprehensive guidance for implementing authentication in DataRobot Agent Templates, covering API tokens, MCP server authentication, authorization context, OAuth 2.0, and security best practices.

## Authentication methods

This section provides an overview of the different authentication methods available in the framework:

| Method | Description | Use Case |
| --- | --- | --- |
| API token authentication | Simple token-based authentication | External APIs, DataRobot services. |
| MCP server authentication | Automatic token-based authentication for MCP servers | MCP tool integration. |
| OAuth 2.0 | Standard OAuth for external services | Third-party integrations. |

## API token authentication

API token authentication is the most common method for authenticating with DataRobot services and external APIs. It uses bearer tokens passed in headers or environment variables.

### DataRobot API authentication

Configure API tokens using environment variables or programmatically. The `DATAROBOT_API_TOKEN` is available in the [API keys and tools section of your account settings](https://docs.datarobot.com/en/docs/platform/acct-settings/api-key-mgmt.html).

**Environment variables (recommended):**
The agent templates automatically use `DATAROBOT_API_TOKEN` and `DATAROBOT_ENDPOINT` environment variables when they are set. This is the recommended approach as it keeps credentials out of your code and works seamlessly with `MyAgent` initialization. The `MyAgent` class automatically falls back to these environment variables if credentials aren't provided explicitly. When using the optional `ToolClient` class for external tool integration, it also uses these environment variables by default. MCP servers also use `DATAROBOT_API_TOKEN` automatically for authentication.

```
DATAROBOT_API_TOKEN=<your_api_key>
DATAROBOT_ENDPOINT=https://app.datarobot.com
```

**Programmatic:**
You can pass API credentials directly when initializing the `MyAgent` class. This is useful when you need to override environment variables or use different credentials for specific instances. The `MyAgent` class will still fall back to environment variables if parameters are not provided.

```
from agent import MyAgent

agent = MyAgent(
    api_key="your_api_key",
    api_base="https://app.datarobot.com"
)
```

> [!NOTE] ToolClient and MCP tools for external tools
> If you're integrating external tools using the `ToolClient` class from the `datarobot-genai` package, you can also pass credentials programmatically. For MCP server-based tool integration, authentication is handled automatically via `DATAROBOT_API_TOKEN`. See the [tool integration documentation](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-tools-integrate.html) and [MCP tools documentation](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html) for details.


### External API authentication

When creating custom tools that need to authenticate with external APIs, retrieve API keys from environment variables or runtime parameters within your tool's `run()` method. This keeps credentials out of your source code and follows the same security pattern used throughout the agent templates.

For local development, use environment variables. For deployed agents, define runtime parameters in `model-metadata.yaml` and retrieve them using `RuntimeParameters.get()` from `datarobot_drum`. Try `os.environ.get()` first (for local development), then fall back to `RuntimeParameters.get()` for deployed agents., as shown in the example below:

```
# custom-tool-example.py
import os
import requests
from crewai.tools import BaseTool
from datarobot_drum import RuntimeParameters

class ExternalAPITool(BaseTool):
    def run(self, query: str) -> str:
        api_key = os.environ.get("EXTERNAL_API_KEY")
        if not api_key:
            api_key = RuntimeParameters.get("EXTERNAL_API_KEY")["apiToken"]

        headers = {"Authorization": f"Bearer {api_key}"}
        response = requests.get(
            "https://api.external-service.com/data",
            headers=headers,
            params={"query": query}
        )
        return response.json()
```

> [!NOTE] Define runtime parameters for deployment
> To use runtime parameters in deployed agents, define them in your `model-metadata.yaml` file. For credential-type parameters (like API keys), use `type: credential`:
> 
> ```
> runtimeParameterDefinitions:
>   - fieldName: EXTERNAL_API_KEY
>     type: credential
>     credentialType: api_token
>     description: API key for external service authentication
> ```
> 
> See the [runtime parameters documentation](https://docs.datarobot.com/en/docs/api/code-first-tools/drum/custom-model-runtime-parameters.html) for more details on configuration options.

### MCP server authentication

When using MCP (Model Context Protocol) servers to provide tools to your agents, authentication is handled automatically using the `DATAROBOT_API_TOKEN` environment variable. The MCP client in the agent templates automatically uses this token for authenticated requests to the MCP server.

Configuration:

```
# .env
DATAROBOT_API_TOKEN=<your_api_key>
DATAROBOT_ENDPOINT=https://app.datarobot.com
```

The MCP client will automatically use `DATAROBOT_API_TOKEN` when making requests to the MCP server. No additional configuration is required beyond setting these environment variables.

> [!NOTE] MCP vs. ToolClient authentication
> MCP tools use `DATAROBOT_API_TOKEN` directly for server authentication, while `ToolClient` (used for direct tool deployments) can use both API tokens and authorization context. For more information about MCP tool integration, see [Integrate tools using an MCP server](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html).

## Authorization context

The framework provides an authorization context system for propagating authentication information to downstream tools and services. This allows tokens and credentials to be automatically passed between agent tools without manual configuration.

Initialize authorization context in your agent's `chat()` function using `resolve_authorization_context()` from the `datarobot-genai` package. The function returns the authorization context dictionary, which should be assigned to `completion_create_params["authorization_context"]`. Tools can then retrieve the context using `get_authorization_context()` from the `datarobot` SDK:

```
# custom.py
from datarobot_genai.core.chat import resolve_authorization_context
from datarobot.models.genai.agent.auth import get_authorization_context

def chat(completion_create_params, load_model_result, **kwargs):
    # Initialize the authorization context for downstream agents and tools
    completion_create_params["authorization_context"] = resolve_authorization_context(
        completion_create_params, **kwargs
    )
    # ... rest of chat function

# In your tools
auth_context = get_authorization_context()
access_token = auth_context.get("access_token")
```

> [!NOTE] ToolClient and MCP tools with authorization context
> When using the optional `ToolClient` class from the `datarobot-genai` package for external tool integration, it automatically propagates authorization context when calling agent tools. MCP tools use `DATAROBOT_API_TOKEN` directly for authentication and don't require authorization context propagation. See the [tool integration documentation](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-tools-integrate.html) and [MCP tools documentation](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html) for details.

## OAuth 2.0 authentication

For external services that support OAuth 2.0, implement OAuth flows in your tools. Create an OAuth application in the service's developer console and set environment variables:

```
# .env
OAUTH_CLIENT_ID=<your_client_id>
OAUTH_CLIENT_SECRET=<your_client_secret>
OAUTH_REDIRECT_URI=<your_redirect_uri>
OAUTH_SCOPE=<required_scopes>
```

Then, use those environment variables in the OAuth implementation. This example demonstrates a complete OAuth 2.0 authorization code flow for a CrewAI tool. The tool inherits from `crewai.tools.BaseTool` (the standard base class for tools in CrewAI agent templates), manages its own token lifecycle with in-memory caching, and follows the repository's pattern of retrieving credentials from environment variables.

> [!NOTE] Example implementation
> Note that this is a CrewAI-specific framework example illustrating a basic OAuth authentication pattern. The `run()` method makes a placeholder API call to demonstrate token usage, but you'll need to implement actual tool logic based on your specific use case.

```
# custom-tool-example.py
import os
import time
import requests
from urllib.parse import urlencode
from crewai.tools import BaseTool

class ExampleToolWithOAuth(BaseTool):
    def __init__(self):
        super().__init__()
        self.client_id = os.getenv("OAUTH_CLIENT_ID")
        self.client_secret = os.getenv("OAUTH_CLIENT_SECRET")
        self.redirect_uri = os.getenv("OAUTH_REDIRECT_URI")
        self._access_token = None
        self._token_expires_at = None

    def get_authorization_url(self) -> str:
        params = {
            "client_id": self.client_id,
            "redirect_uri": self.redirect_uri,
            "response_type": "code",
            "scope": "read:data"
        }
        return f"https://oauth.provider.com/authorize?{urlencode(params)}"

    def exchange_code_for_token(self, code: str) -> dict:
        response = requests.post(
            "https://oauth.provider.com/token",
            data={
                "grant_type": "authorization_code",
                "client_id": self.client_id,
                "client_secret": self.client_secret,
                "code": code,
                "redirect_uri": self.redirect_uri
            }
        )
        token_data = response.json()
        self._access_token = token_data.get("access_token")
        expires_in = token_data.get("expires_in", 3600)
        self._token_expires_at = time.time() + expires_in
        return token_data

    def get_cached_access_token(self) -> str:
        if self._access_token and self._token_expires_at and time.time() < self._token_expires_at:
            return self._access_token
        # Token expired or not set - refresh or re-authenticate
        # In production, implement token refresh logic here
        raise ValueError("Access token expired. Re-authenticate to get a new token.")

    def run(self, query: str) -> str:
        access_token = self.get_cached_access_token()
        response = requests.get(
            "https://api.provider.com/data",
            headers={"Authorization": f"Bearer {access_token}"},
            params={"query": query}
        )
        return response.json()
```

## Security best practices

Following security best practices is essential when handling authentication in production environments. Adhere to the following guidelines:

- API token authentication
- Store tokens in environment variables; never hard code secrets in source code.
- Use secure token storage solutions in production environments.
- Implement token rotation and enforce token expiration policies.
- Validate authorization context before using it in tools.
- Follow least-privilege access principles.
- Log authentication events for audit purposes.
- OAuth 2.0
- Use HTTPS for all OAuth communications.
- Validate the state parameter to prevent Cross-Site Request Forgery (CSRF) attacks.
- Store refresh tokens securely.
- Handle token expiration and refresh logic reliably.
- Validate authorization context before use.
- General Security
- Use separate environments for development and production.
- Implement robust secret management practices.
- Follow container security best practices.
- Conduct regular security audits and apply updates.

## Troubleshooting authentication issues

This section helps you diagnose and resolve common authentication problems when developing or deploying agents.

### Common issues

The following sections describe common authentication errors and how to resolve them:

#### Missing API token

This error occurs when the DataRobot API token is not configured.

Issue: `Error: Missing DataRobot API token. Set the DATAROBOT_API_TOKEN environment variable`

Solution: Set the `DATAROBOT_API_TOKEN` environment variable to use your [DataRobot API key](https://docs.datarobot.com/en/docs/platform/acct-settings/api-key-mgmt.html).

#### Invalid endpoint

This error occurs when the DataRobot endpoint is missing or incorrectly configured.

Issue: `Error: Missing DataRobot endpoint. Set the DATAROBOT_ENDPOINT environment variable`

Solution: Set the correct `DATAROBOT_ENDPOINT` environment variable.

#### Authorization context not set

This error occurs when tools try to access the authorization context before it has been initialized.

Issue: `Error: Authorization context not available for tool`

Solution: Ensure `resolve_authorization_context()` is called in your agent's `chat()` function and the result is assigned to `completion_create_params["authorization_context"]`.

#### OAuth token expired

This error occurs when an OAuth access token has expired and needs to be refreshed.

Issue: `Error: 401 Unauthorized`

Solution: Implement token refresh logic or re-authenticate.

#### MCP server authentication failure

This error occurs when the MCP server cannot authenticate the agent's requests.

Issue: `Error: 401 Unauthorized` or `MCP connection failures`

Solutions:

1. Verify API token : Ensure DATAROBOT_API_TOKEN is set correctly in your environment
2. Check token permissions : Verify the token has necessary permissions for MCP server access
3. Verify MCP server endpoint : Check that the MCP server endpoint is correct
4. For local development : Ensure the MCP server is running and accessible
5. Review MCP configuration : See MCP tools troubleshooting for more details

### Debugging tips

Useful techniques for debugging authentication issues:

#### Enable verbose logging

Enable verbose logging to get detailed information about authentication operations. To do so, search for where `MyAgent` is instantiated in `custom.py` and set `verbose=True`.

```
# custom.py
from agent import MyAgent

# ...

agent = MyAgent(verbose=True, **completion_create_params)
```

#### Check environment variables

Verify that required environment variables are set correctly.

```
import os
print(f"API Token: {os.getenv('DATAROBOT_API_TOKEN')}")
print(f"Endpoint: {os.getenv('DATAROBOT_ENDPOINT')}")
```

#### Test authentication

Test authentication using the `AgentEnvironment` class from `datarobot_genai.core.cli`:

```
from datarobot_genai.core.cli import AgentEnvironment

try:
    env = AgentEnvironment()
    print("Authentication successful")
except ValueError as e:
    print(f"Authentication failed: {e}")
```

#### Validate authorization context

Check authorization context using `get_authorization_context()` from `datarobot.models.genai.agent.auth`:

```
# custom-tool-example.py
from datarobot.models.genai.agent.auth import get_authorization_context

auth_context = get_authorization_context()
print(f"Authorization context: {auth_context}")
```