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

# Authenticating

> How to generate and use API keys to allow your agent to access protected or paid services.

Many services in the App Store, especially those that require payment, are protected. To use them, your agent must present a valid credential.

The primary method for programmatic clients like AI agents is a long-lived **API Key**. However, for user-facing applications (like a desktop app or IDE plugin), a browser-based **OAuth 2.1 Login** flow is also supported. This guide covers both.

### Primary Method: API Keys for Autonomous Agents

This process is designed for non-interactive use cases like backend services or autonomous agents. As the user running the agent, you will perform a one-time setup in the App Store UI to provision a key. Your agent then uses this key for all subsequent requests.

<Steps>
  <Step title="1. Set a Spending Allowance">
    Before your agent can use a paid service, you must authorize it to spend funds on your behalf. This is done by setting an allowance.

    1. Navigate to the service's detail page in the Prometheus App Store.
    2. Find the "Access & Billing" section.
    3. Click "Manage Allowance" and approve a spending limit with your wallet. This is a non-custodial `icrc2_approve` transaction; funds remain in your wallet until they are spent.
  </Step>

  <Step title="2. Generate an API Key">
    Once the allowance is set, you can create an API key.

    1. In the same "Access & Billing" section, click "Create API Key".
    2. Give the key a descriptive name (e.g., "My-Claude-Agent-Key").
    3. The new key will be displayed on your screen.

    <Warning>
      **Copy this key immediately and store it securely!** For your security, this is the only time the full key will be visible.
    </Warning>
  </Step>

  <Step title="3. Configure Your Agent">
    With the API key copied, the final step is to provide it to your agent or SDK. The key must be sent in the `x-api-key` header of every request.
  </Step>
</Steps>

#### SDK Implementation (API Key)

If you are building a custom client with the `@modelcontextprotocol/sdk`, you provide the API key when you create the transport layer.

```typescript theme={null}
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

// The URL of the protected service from the App Store
const serviceUrl = 'https://<canister_id>.icp0.io/mcp/';

// Your securely stored API key
const apiKey = 'prom_sk_123abc...';

const client = new Client({ name: 'my-custom-agent', version: '1.0.0' });

// Pass the API key in the 'x-api-key' header when creating the transport
const transport = new StreamableHTTPClientTransport(new URL(serviceUrl), {
  headers: {
    'x-api-key': apiKey,
  },
});

// This call now connects directly without any browser interaction.
await client.connect(transport);
```

***

### Optional: Interactive Login for User-Facing Applications

While API keys are ideal for autonomous agents, the Prometheus SDK also supports a browser-based OAuth 2.1 flow. This method is designed for applications where a **user is present** to interactively log in and grant consent.

#### The Seamless Login Flow

You do not need to manually register clients or handle tokens. The SDK manages the entire process.

<Steps>
  <Step title="Connection is Attempted">
    Your application attempts to connect to the protected MCP server.
  </Step>

  <Step title="Login Prompt Appears">
    The SDK detects the need for authentication and automatically opens a
    browser window, prompting the user to log in and grant your application
    consent.
  </Step>

  <Step title="User Grants Consent">
    The user logs in with their identity and approves the permissions (e.g.,
    "Allow this agent to spend tokens on my behalf").
  </Step>

  <Step title="Connection Succeeds">
    Once consent is granted, the browser window closes. The SDK securely
    receives an access token in the background and automatically retries the
    connection, which now succeeds.
  </Step>
</Steps>

#### SDK Implementation (Interactive Login)

To trigger this flow, simply attempt to connect **without** providing an API key. The SDK handles the rest.

```typescript theme={null}
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

// The URL of the protected service from the App Store
const serviceUrl = 'https://<canister_id>.icp0.io/mcp/';

const client = new Client({ name: 'my-custom-agent', version: '1.0.0' });

// Create the transport WITHOUT any authentication headers
const transport = new StreamableHTTPClientTransport(new URL(serviceUrl));

// This single call handles everything.
// If authentication is needed, it will trigger the browser flow.
await client.connect(transport);

// You are now connected and authenticated.
// The SDK will automatically manage tokens for all subsequent calls.
const result = await client.callTool({ name: 'some_paid_tool' });
```

***