Taskfolk Authentication

generated: '2026-08-20'
method: searched
source: openapi/taskfolk-product-api-openapi.yml
docs: https://taskfolk.ai/auth.md
discovery:
  authorization_server: https://taskfolk.ai/.well-known/oauth-authorization-server
  protected_resource: https://taskfolk.ai/.well-known/oauth-protected-resource
  agent_card: https://taskfolk.ai/.well-known/agent-card.json
summary:
  types: [http, oauth2]
  http_schemes: [bearer]
  api_key_in: [header]
  oauth2_flows: [authorizationCode]
  pkce: required (S256)
  dynamic_client_registration: true
note: >-
  The derived pass found ONE scheme (bearerAuth) because that is all the OpenAPI declares.
  The docs pass adds the OAuth 2.0 authorization server, which is real and fully described in
  RFC 8414 / RFC 9728 discovery documents but is absent from the contract's securitySchemes.
  Both credential types resolve to the same `Authorization: Bearer` header on the wire, and
  the same token works on REST and MCP.
schemes:
  - name: bearerAuth
    type: http
    scheme: bearer
    bearerFormat: API key
    in: header
    key_prefix: tfk_live_
    description: >-
      Workspace API key. Each key is bound to exactly one workspace and carries a set of
      scopes. Shown in full exactly once at creation. A key acts as the user who created it,
      so an agent's writes are attributed to that identity; the provider recommends one key
      per agent.
    minted_at: Workspace → Developer → Keys (and https://taskfolk.ai/me for personal access tokens)
    controls: [per-key adjustable rate limit, per-key Usage tab, per-key Audit tab, anomaly detection email, revocation email]
    sources: [openapi/taskfolk-product-api-openapi.yml, https://taskfolk.ai/auth.md]
  - name: oauth2
    type: oauth2
    declared_in_openapi: false
    issuer: https://taskfolk.ai
    flows:
      - flow: authorizationCode
        authorizationUrl: https://taskfolk.ai/api/oauth/authorize
        tokenUrl: https://taskfolk.ai/api/oauth/token
        refreshUrl: https://taskfolk.ai/api/oauth/token
        scopes_count: 47
        pkce: S256 required on every code exchange
    revocation_endpoint: https://taskfolk.ai/api/oauth/revoke
    registration_endpoint: https://taskfolk.ai/api/oauth/register
    grant_types: [authorization_code, refresh_token]
    token_endpoint_auth_methods: [none, client_secret_post]
    access_token_ttl: 1 hour
    refresh_token_ttl: 30 days
    sources: [https://taskfolk.ai/.well-known/oauth-authorization-server, https://taskfolk.ai/auth.md]
    detail: scopes/taskfolk-scopes.yml
  - name: personal-access-token
    type: http
    scheme: bearer
    description: >-
      Long-lived human-minted token at https://taskfolk.ai/me, handed to an agent. Inherits
      the creator's role ceiling and chosen scopes.
    sources: [https://taskfolk.ai/auth.md, https://taskfolk.ai/.well-known/agent-card.json]
agent_onboarding:
  anonymous_registration: true
  flow: >-
    1) discover the AS metadata, 2) POST an unauthenticated RFC 7591 client registration
    naming the target workspace slug, 3) send the user through the claim ceremony
    (authorization_code + PKCE S256) where they sign in passwordlessly and approve the
    scopes, 4) exchange the code, 5) call REST or MCP with the same Bearer token,
    6) refresh, 7) revoke (RFC 7009).
  human_consent_required: true
  revocable_by_user: Workspace Developer dashboard; revoked credentials fail with an opaque 401.
  machine_readable_at: agent_auth block inside the RFC 8414 metadata
  docs: https://taskfolk.ai/auth.md
challenge_observed:
  url: https://taskfolk.ai/api/mcp/v1
  http_status: 401
  www_authenticate: 'Bearer realm="taskfolk-product", resource_metadata="https://taskfolk.ai/.well-known/oauth-protected-resource"'
  note: RFC 9728-compliant challenge — the 401 points a client straight at the protected-resource metadata.