Akhrot

# Akhrot - OAuth Integration Skill for AI Agents

You have access to Akhrot, an OAuth-as-a-Service platform that lets you connect to and use OAuth-protected APIs (e.g. Google: Gmail, Drive, Calendar) and API key providers. See /docs/providers for the enabled list.

## Base Configuration

- **Base URL**: https://akhrot.ai
- **API Key Format**: `akhrot_xxx_yyy` (get from dashboard)
- **Authentication**: All API requests require `Authorization: Bearer YOUR_API_KEY` header

## Quick Start Workflow

### Step 1: Check Connection Status (ALWAYS START HERE)
Use the **lightweight summary** endpoint first (~500 bytes vs ~50KB):

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://akhrot.ai/ai/context/summary"
```

Returns which providers are connected and their available services.

### Step 1b: Get Provider/Service Details (When Needed)
Only fetch full capabilities when you need them:

```bash
# Get specific provider (e.g., google with gmail, drive, calendar)
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://akhrot.ai/ai/context/google"

# Get specific service only (most efficient)
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://akhrot.ai/ai/context/google/gmail"
```

### Step 2: For connected Providers - Get Token
Use the `getToken.curl` command from context response, or:

```bash
curl -X POST "https://akhrot.ai/tokens/fetch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "google"}'
```

Response:
```json
{
  "status": "success",
  "data": {
    "accessToken": "ya29.xxx...",
    "expiresAt": "2024-01-15T12:00:00.000Z",
    "scope": ["gmail.readonly", "drive.readonly"],
    "providerEmail": "user@gmail.com"
  }
}
```

### Step 3: Use Token with Provider API
Use the `accessToken` directly with the provider's API:

```bash
curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://gmail.googleapis.com/gmail/v1/users/me/messages?maxResults=10"
```

### Step 4: For Disconnected Providers - Connect
If a provider isn't connected, use the `connect.curl` from context, or:

```bash
curl -X POST "https://akhrot.ai/oauth/sessions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "github",
    "redirectUri": "https://yourapp.com/callback"
  }'
```

Response includes a `url` - the user MUST visit this URL to authorize. You cannot authorize on their behalf.

## Key Points

1. **Start with `/ai/context/summary`** - Lightweight connection status (~500 bytes)
2. **Fetch details only when needed** - `/ai/context/{provider}` or `/ai/context/{provider}/{service}`
3. **Tokens auto-refresh** - Just call `/tokens/fetch`, expired tokens refresh automatically
4. **User action required for OAuth** - You CANNOT authorize on behalf of users, they must visit the OAuth URL