# TapAuth — Full Documentation

> Human-approved delegated access for AI agents. TapAuth lets AI agents request OAuth access tokens through a human-in-the-loop approval flow.

## What TapAuth Does

TapAuth is an access gateway for AI agents. An agent requests access to a user's account (Google Calendar, GitHub, Google Sheets, etc.), the user approves with specific scopes, and the agent receives a short-lived OAuth access token.

## Supported Providers

- Google (View calendar events, Create & edit calendar events, View calendar events (events-only), View spreadsheets, Edit spreadsheets, View documents, Edit documents)
- Google Sheets (View spreadsheets, Edit spreadsheets)
- Google Docs (View documents, Edit documents)
- GitHub (Access public repositories, Access private repositories (full), Read user profile, Access user email addresses, Read org membership, Create and manage gists, Access notifications, Update GitHub Actions workflows, Full control of organizations, Delete repositories)
- Linear (Read issues & projects, Create & edit issues, Create issues, Create comments)
- Vercel (View and manage deployments, Access project details, Manage environment variables, Manage domains, Access team info, Read user profile)
- Slack (View people in workspace, View email addresses of people, View basic channel info, View messages in public channels, View basic private channel info, View basic DM info, View files shared in channels, Search messages, View workspace info)
- Notion (Read pages & databases, Update existing content, Create new content, Read user info with email)
- Asana (Read tasks, Create and update tasks, Delete tasks, Read projects, Create and update projects, Delete projects, Read user information, Read teams, Read workspaces, Read attachments, Upload attachments, Delete attachments, Read stories (comments), Create and update stories, Read tags, Create and update tags, Read custom fields, Create and update custom fields, Read portfolios, Create and update portfolios, Read goals, Read webhooks, Create and update webhooks, Delete webhooks, Verify your identity (OpenID), View your email address, View your profile info)
- Sentry (View organization details, Modify organization settings, View project details, Modify project settings, Manage releases, View team details, Modify teams, View organization members, Invite and modify members, View events and issues, Modify events (resolve, merge))
- Discord (View your username and avatar, View your email address, View your server list)

## Authentication Flow

1. **Agent requests a grant:** POST /api/v1/grants with provider and scopes
2. **TapAuth returns a grant ID and approval URL:** The agent receives a `grant_id`, `grant_secret`, and an `approve_url`
3. **User visits the approval URL:** The user sees which scopes the agent is requesting and approves or denies
4. **User completes OAuth:** After approval, the user authenticates with the provider (e.g., Google, GitHub)
5. **Agent polls for the token:** GET /api/v1/token/{id} with Bearer auth — once approved, the response includes the access token

## API Endpoints

Base URL: `https://tapauth.ai`

### POST /api/v1/grants — Create a Grant Request

Request a new OAuth grant. The agent specifies which provider and scopes it needs.

**Request body (JSON):**
```json
{
  "provider": "google",
  "scopes": ["calendar.readonly", "spreadsheets.readonly"]
}
```

**Response (JSON):**
```json
{
  "grant_id": "grant_abc123",
  "grant_secret": "gs_xK9m...",
  "approve_url": "https://tapauth.ai/approve/grant_abc123",
  "status": "pending_registration"
}
```

### GET /api/v1/token/{id} — Retrieve the Token

Poll for the access token using Bearer auth with the grant_secret.

**Request:**
```bash
curl https://tapauth.ai/api/v1/token/{grant_id} \
  -H "Authorization: Bearer gs_xK9m..."
```

**Response (200 — approved):** Plain text access token
```
ya29.a0...
```

**Response (202):** Pending — user hasn't approved yet. Poll again in 2-5 seconds.

**Response (.json format):**
```json
{
  "token": "ya29.a0...",
  "expires": "2026-03-05T17:00:00Z",
  "provider": "google",
  "grant_id": "grant_abc123"
}
```

### GET /api/providers — List Available Providers

Returns all supported providers and their available scopes.

## Provider Details

### Google (`google`)

- OAuth type: google
- PKCE: no
- Scope model: per-request
- Available scopes:
  - `calendar.readonly` — View calendar events (OAuth: `calendar.readonly`)
  - `calendar.events` — Create & edit calendar events (OAuth: `calendar.events`)
  - `calendar.events.readonly` — View calendar events (events-only) (OAuth: `calendar.events.readonly`)
  - `spreadsheets.readonly` — View spreadsheets (OAuth: `spreadsheets.readonly`)
  - `spreadsheets` — Edit spreadsheets (OAuth: `spreadsheets`)
  - `documents.readonly` — View documents (OAuth: `documents.readonly`)
  - `documents` — Edit documents (OAuth: `documents`)

### Google Sheets (`google_sheets`)

- OAuth type: google
- PKCE: no
- Scope model: per-request
- Available scopes:
  - `spreadsheets.readonly` — View spreadsheets (OAuth: `spreadsheets.readonly`)
  - `spreadsheets` — Edit spreadsheets (OAuth: `spreadsheets`)

### Google Docs (`google_docs`)

- OAuth type: google
- PKCE: no
- Scope model: per-request
- Available scopes:
  - `documents.readonly` — View documents (OAuth: `documents.readonly`)
  - `documents` — Edit documents (OAuth: `documents`)

### GitHub (`github`)

- OAuth type: github
- PKCE: no
- Scope model: per-request
- Available scopes:
  - `public_repo` — Access public repositories (OAuth: `public_repo`)
  - `repo` — Access private repositories (full) (OAuth: `repo`)
  - `read:user` — Read user profile (OAuth: `read:user`)
  - `user:email` — Access user email addresses (OAuth: `user:email`)
  - `read:org` — Read org membership (OAuth: `read:org`)
  - `gist` — Create and manage gists (OAuth: `gist`)
  - `notifications` — Access notifications (OAuth: `notifications`)
  - `workflow` — Update GitHub Actions workflows (OAuth: `workflow`)
  - `admin:org` — Full control of organizations (OAuth: `admin:org`)
  - `delete_repo` — Delete repositories (OAuth: `delete_repo`)

### Linear (`linear`)

- OAuth type: linear
- PKCE: yes
- Scope model: per-request
- Available scopes:
  - `read` — Read issues & projects (OAuth: `read`)
  - `write` — Create & edit issues (OAuth: `write`)
  - `issues:create` — Create issues (OAuth: `issues:create`)
  - `comments:create` — Create comments (OAuth: `comments:create`)

### Vercel (`vercel`)

- OAuth type: vercel
- PKCE: no
- Scope model: integration-level
- Available scopes:
  - `deployment` — View and manage deployments (OAuth: `deployment`)
  - `project` — Access project details (OAuth: `project`)
  - `project-env-vars` — Manage environment variables (OAuth: `project-env-vars`)
  - `domain` — Manage domains (OAuth: `domain`)
  - `team` — Access team info (OAuth: `team`)
  - `user` — Read user profile (OAuth: `user`)

### Slack (`slack`)

- OAuth type: slack
- PKCE: no
- Scope model: integration-level
- Available scopes:
  - `users:read` — View people in workspace (OAuth: `users:read`)
  - `users:read.email` — View email addresses of people (OAuth: `users:read.email`)
  - `channels:read` — View basic channel info (OAuth: `channels:read`)
  - `channels:history` — View messages in public channels (OAuth: `channels:history`)
  - `groups:read` — View basic private channel info (OAuth: `groups:read`)
  - `im:read` — View basic DM info (OAuth: `im:read`)
  - `files:read` — View files shared in channels (OAuth: `files:read`)
  - `search:read` — Search messages (OAuth: `search:read`)
  - `team:read` — View workspace info (OAuth: `team:read`)

### Notion (`notion`)

- OAuth type: notion
- PKCE: no
- Scope model: integration-level
- Available scopes:
  - `read_content` — Read pages & databases (OAuth: `read_content`)
  - `update_content` — Update existing content (OAuth: `update_content`)
  - `insert_content` — Create new content (OAuth: `insert_content`)
  - `read_user_with_email` — Read user info with email (OAuth: `read_user_with_email`)

### Asana (`asana`)

- OAuth type: asana
- PKCE: yes
- Scope model: per-request
- Available scopes:
  - `tasks:read` — Read tasks (OAuth: `tasks:read`)
  - `tasks:write` — Create and update tasks (OAuth: `tasks:write`)
  - `tasks:delete` — Delete tasks (OAuth: `tasks:delete`)
  - `projects:read` — Read projects (OAuth: `projects:read`)
  - `projects:write` — Create and update projects (OAuth: `projects:write`)
  - `projects:delete` — Delete projects (OAuth: `projects:delete`)
  - `users:read` — Read user information (OAuth: `users:read`)
  - `teams:read` — Read teams (OAuth: `teams:read`)
  - `workspaces:read` — Read workspaces (OAuth: `workspaces:read`)
  - `attachments:read` — Read attachments (OAuth: `attachments:read`)
  - `attachments:write` — Upload attachments (OAuth: `attachments:write`)
  - `attachments:delete` — Delete attachments (OAuth: `attachments:delete`)
  - `stories:read` — Read stories (comments) (OAuth: `stories:read`)
  - `stories:write` — Create and update stories (OAuth: `stories:write`)
  - `tags:read` — Read tags (OAuth: `tags:read`)
  - `tags:write` — Create and update tags (OAuth: `tags:write`)
  - `custom_fields:read` — Read custom fields (OAuth: `custom_fields:read`)
  - `custom_fields:write` — Create and update custom fields (OAuth: `custom_fields:write`)
  - `portfolios:read` — Read portfolios (OAuth: `portfolios:read`)
  - `portfolios:write` — Create and update portfolios (OAuth: `portfolios:write`)
  - `goals:read` — Read goals (OAuth: `goals:read`)
  - `webhooks:read` — Read webhooks (OAuth: `webhooks:read`)
  - `webhooks:write` — Create and update webhooks (OAuth: `webhooks:write`)
  - `webhooks:delete` — Delete webhooks (OAuth: `webhooks:delete`)
  - `openid` — Verify your identity (OpenID) (OAuth: `openid`)
  - `email` — View your email address (OAuth: `email`)
  - `profile` — View your profile info (OAuth: `profile`)

### Sentry (`sentry`)

- OAuth type: sentry
- PKCE: yes
- Scope model: per-request
- Available scopes:
  - `org:read` — View organization details (OAuth: `org:read`)
  - `org:write` — Modify organization settings (OAuth: `org:write`)
  - `project:read` — View project details (OAuth: `project:read`)
  - `project:write` — Modify project settings (OAuth: `project:write`)
  - `project:releases` — Manage releases (OAuth: `project:releases`)
  - `team:read` — View team details (OAuth: `team:read`)
  - `team:write` — Modify teams (OAuth: `team:write`)
  - `member:read` — View organization members (OAuth: `member:read`)
  - `member:write` — Invite and modify members (OAuth: `member:write`)
  - `event:read` — View events and issues (OAuth: `event:read`)
  - `event:write` — Modify events (resolve, merge) (OAuth: `event:write`)

### Discord (`discord`)

- OAuth type: discord
- PKCE: no
- Scope model: per-request
- Available scopes:
  - `identify` — View your username and avatar (OAuth: `identify`)
  - `email` — View your email address (OAuth: `email`)
  - `guilds` — View your server list (OAuth: `guilds`)

## Code Examples

### Create a grant (curl)

```bash
curl -X POST https://tapauth.ai/api/v1/grants \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "scopes": ["calendar.readonly"]
  }'
```

### Create a grant (JavaScript)

```javascript
const response = await fetch('https://tapauth.ai/api/v1/grants', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    provider: 'google',
    scopes: ['calendar.readonly'],
  }),
});
const { grant_id, grant_secret, approve_url } = await response.json();
```

### Retrieve token (curl)

```bash
curl https://tapauth.ai/api/v1/token/grant_abc123 \
  -H "Authorization: Bearer gs_xK9m..."
```

### Retrieve token (JavaScript)

```javascript
const res = await fetch(`https://tapauth.ai/api/v1/token/${grant_id}`, {
  headers: { 'Authorization': `Bearer ${grant_secret}` },
});
if (res.ok) {
  const token = await res.text();
  console.log('Token:', token);
}
```

## CLI Script — Shell Wrapper

TapAuth provides a zero-dependency bash script that wraps the entire grant → approve → token flow:

```bash
# Save the script and make executable
curl -sf https://tapauth.ai/cli/tapauth > tapauth && chmod +x tapauth

# Use inline — token on stdout, status on stderr
curl -H "Authorization: Bearer $(./tapauth google calendar.events)" \
  https://www.googleapis.com/calendar/v3/calendars/primary/events
```

**How it works:**
- **First run:** POSTs to /api/v1/grants, prints approval URL to stderr, polls until approved, caches token + grant secret locally
- **Subsequent runs:** Returns cached token instantly (no network call if not expired); auto-refreshes expired tokens

**Environment variables:**
- `TAPAUTH_BASE_URL` — Override base URL (default: https://tapauth.ai)
- `TAPAUTH_HOME` — Override cache directory (default: ./.tapauth)

**Security:** Cache directory mode 700, files mode 600. Grant secrets stored locally for automatic refresh.

RECOMMENDED: Use the CLI script. It handles credential storage, caching, and keeps secrets out of your context.
Set a timeout of at least 600 seconds (10 minutes) when running the CLI, as users may take time to approve.
Do NOT fall back to raw API calls if the CLI times out — this exposes grant secrets to your context.

Full CLI docs: https://tapauth.ai/docs

## Rate Limits and Constraints

- **Token expiry:** Access tokens are short-lived (typically 1 hour for Google, varies by provider)
- **Polling:** Recommended polling interval is 2–5 seconds. Do not poll more than once per second.
- **Grant expiry:** Unapproved grants expire after 30 minutes
- **No authentication required** to access /llms.txt or /llms-full.txt

## Links

- Docs: https://tapauth.ai/docs
- Concise LLM docs: https://tapauth.ai/llms.txt
- Website: https://tapauth.ai