# Taskfolk auth.md

Taskfolk is a project management platform. This document tells AI agents how to
register and authenticate, start to finish. Machine-readable metadata lives in
the agent_auth block of the
[authorization server metadata](https://taskfolk.ai/.well-known/oauth-authorization-server)
and the
[protected resource metadata](https://taskfolk.ai/.well-known/oauth-protected-resource).

## Agent registration (complete flow)

Anonymous agents register an OAuth client, then obtain user-delegated tokens
through a claim ceremony (authorization code + PKCE). No pre-existing account
or API key is needed to begin.

### 1. Discover

Fetch the [authorization server metadata](https://taskfolk.ai/.well-known/oauth-authorization-server).
The agent_auth block advertises: register_uri, identity_types_supported
(anonymous), claim_uri, and revocation_uri. Issuer: https://taskfolk.ai

### 2. Register (anonymous, RFC 7591)

POST to the registration endpoint at https://taskfolk.ai/api/oauth/register

```bash
curl -s -X POST https://taskfolk.ai/api/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My Agent",
    "workspace": "your-workspace-slug",
    "redirect_uris": ["https://your-agent.example.com/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "token_endpoint_auth_method": "none",
    "scope": "read write"
  }'
```

The response contains client_id. The workspace field names the workspace
slug the agent wants access to (its user will confirm this during the claim
ceremony). Registration is unauthenticated by design and rate limited per
IP and per workspace.

### 3. Claim ceremony (user verification)

Send the user to the claim URI so they can verify the agent and consent.
Build the URL from the authorization endpoint at https://taskfolk.ai/api/oauth/authorize
with PKCE (S256):

```text
https://taskfolk.ai/api/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=https://your-agent.example.com/callback&scope=read+write&state=RANDOM_STATE&code_challenge=BASE64URL_S256_OF_VERIFIER&code_challenge_method=S256
```

The user signs in (passwordless magic link) and approves the requested
scopes for the workspace named at registration. Taskfolk redirects back to
redirect_uri with an authorization code bound to that user and workspace.

### 4. Exchange the code for credentials

POST to the token endpoint at https://taskfolk.ai/api/oauth/token

```bash
curl -s -X POST https://taskfolk.ai/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code=AUTH_CODE \
  -d redirect_uri=https://your-agent.example.com/callback \
  -d client_id=CLIENT_ID \
  -d code_verifier=PKCE_VERIFIER
```

Returns access_token (Bearer), refresh_token, and expiry. PKCE
(code_challenge_method S256) is required on every code exchange.

### 5. Call the API

```bash
curl -s https://taskfolk.ai/api/v1/me -H "Authorization: Bearer ACCESS_TOKEN"
```

The same Bearer token works for the REST API and the MCP server (streamable
HTTP) listed under API surfaces below.

### 6. Refresh

POST grant_type=refresh_token with the refresh_token and client_id to the
token endpoint at https://taskfolk.ai/api/oauth/token

### 7. Revoke

POST the token to the revocation endpoint (RFC 7009) at https://taskfolk.ai/api/oauth/revoke

```bash
curl -s -X POST https://taskfolk.ai/api/oauth/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d token=ACCESS_TOKEN -d client_id=CLIENT_ID
```

Users can also revoke an agent's access at any time from the workspace
Developer dashboard; revoked credentials fail with an opaque 401.

## Alternative: Personal Access Tokens

Humans can mint long-lived tokens at [https://taskfolk.ai/me](https://taskfolk.ai/me) (Developer, API
Keys) and hand them to an agent. Pass as an Authorization Bearer header.
Tokens inherit the creator's role ceiling and chosen scopes.

## Scopes

| Scope | Access |
|-------|--------|
| read | Read workspaces, projects, issues, comments, members |
| write | Create and update resources |
| admin | Workspace management, billing, settings, agent commerce |

## API surfaces

| Surface | URL | Auth |
|---------|-----|------|
| REST API v1 | [https://taskfolk.ai/api/v1](https://taskfolk.ai/api/v1) | Bearer token |
| MCP Server | https://taskfolk.ai/api/mcp/v1 | Bearer token |
| OpenAPI spec (product API) | [https://taskfolk.ai/api/v1/openapi.json](https://taskfolk.ai/api/v1/openapi.json) | Public |
| Payment discovery (MPP) | [https://taskfolk.ai/openapi.json](https://taskfolk.ai/openapi.json) | Public |
| MCP Server Card | [https://taskfolk.ai/.well-known/mcp/server-card.json](https://taskfolk.ai/.well-known/mcp/server-card.json) | Public |
| A2A Agent Card | [https://taskfolk.ai/.well-known/agent-card.json](https://taskfolk.ai/.well-known/agent-card.json) | Public |
| ACP discovery | [https://taskfolk.ai/.well-known/acp.json](https://taskfolk.ai/.well-known/acp.json) | Public |
| UCP profile | [https://taskfolk.ai/.well-known/ucp](https://taskfolk.ai/.well-known/ucp) | Public |