Anahana OAuth API

openapi: 3.2.0
info:
  title: Anahana agent-facing OAuth API
  version: 1.3.0
  summary: The MCP endpoint, its OAuth 2.1 tier, and the static discovery surfaces on www.anahana.com.
  description: 'Anahana (anahana.com) publishes wellness and spiritual-growth content in 24 languages. This document describes every machine-facing endpoint the site exposes. Everything is read-only and everything it returns is already public on the website — there is no private data, no write action, and no credential required to read anything. The MCP server covers all 24 languages, backed by a public build-time index under /content-index/ that the site regenerates on every deploy. The single dynamic endpoint is `POST /mcp`, a Model Context Protocol server over Streamable HTTP; the rest are static discovery documents. Human-readable companion: https://www.anahana.com/en/ai-agents/resources-for-ai-agents/'
  termsOfService: https://www.anahana.com/en/terms/
  contact:
    name: Anahana
    email: team@anahana.com
    url: https://www.anahana.com/en/contact/
  license:
    name: 'Quote and summarize with attribution: yes. Full republication: no. AI training: yes.'
    url: https://www.anahana.com/robots.txt
servers:
- url: https://www.anahana.com
  description: Production
tags:
- name: OAuth
  description: OAuth 2.1 registered tier. Optional — anonymous access to /mcp is fully supported.
paths:
  /mcp/register:
    post:
      tags:
      - OAuth
      operationId: registerClient
      summary: Dynamic client registration (RFC 7591)
      description: Open registration — no human approval, no pre-existing credential, no waiting. Registering raises the rate limit to 120/min and gives a stable, revocable client identity. It does not change what the three currently published tools return.
      security:
      - {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientMetadata'
      responses:
        '201':
          description: Registered. Returns `client_id`, and `client_secret` for confidential clients.
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Invalid client metadata.
  /mcp/authorize:
    get:
      tags:
      - OAuth
      operationId: authorize
      summary: Authorization endpoint (OAuth 2.1 authorization code + PKCE)
      description: There is no consent screen and no login — nothing user-owned is being delegated, so every valid request from a registered client is auto-approved and answered with a 302 to the client's `redirect_uri` carrying `code` and `state`. Headless agents can read the `Location` header instead of following it.
      security:
      - {}
      parameters:
      - name: response_type
        in: query
        required: true
        schema:
          type: string
          const: code
      - name: client_id
        in: query
        required: true
        schema:
          type: string
      - name: redirect_uri
        in: query
        required: true
        schema:
          type: string
          format: uri
      - name: code_challenge
        in: query
        required: true
        schema:
          type: string
      - name: code_challenge_method
        in: query
        required: true
        schema:
          type: string
          const: S256
      - name: state
        in: query
        required: false
        schema:
          type: string
      - name: scope
        in: query
        required: false
        description: Normalized to `read:content`, the only scope.
        schema:
          type: string
      responses:
        '302':
          description: Redirect to `redirect_uri` with `code` and `state`.
          headers:
            Location:
              schema:
                type: string
                format: uri
        '400':
          description: Unknown client_id or invalid request.
  /mcp/token:
    post:
      tags:
      - OAuth
      operationId: token
      summary: Token endpoint (also handles RFC 7009 revocation)
      security:
      - {}
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum:
                  - authorization_code
                  - refresh_token
                code:
                  type: string
                redirect_uri:
                  type: string
                  format: uri
                code_verifier:
                  type: string
                refresh_token:
                  type: string
                client_id:
                  type: string
                client_secret:
                  type: string
              required:
              - grant_type
      responses:
        '200':
          description: Bearer `access_token` (expires in 1 hour) plus a `refresh_token`.
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Invalid grant.
  /.well-known/oauth-authorization-server:
    get:
      tags:
      - OAuth
      operationId: authorizationServerMetadata
      summary: Authorization server metadata (RFC 8414)
      description: Augmented with an `agent_auth` block describing the self-registration surface.
      security:
      - {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
  /.well-known/oauth-protected-resource:
    get:
      tags:
      - OAuth
      operationId: protectedResourceMetadata
      summary: Protected resource metadata (RFC 9728)
      security:
      - {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
components:
  schemas:
    ClientMetadata:
      type: object
      description: RFC 7591 client metadata.
      properties:
        client_name:
          type: string
        redirect_uris:
          type: array
          items:
            type: string
            format: uri
        grant_types:
          type: array
          items:
            type: string
            enum:
            - authorization_code
            - refresh_token
        response_types:
          type: array
          items:
            type: string
            const: code
        token_endpoint_auth_method:
          type: string
          enum:
          - client_secret_post
          - client_secret_basic
          - none
          description: '`none` for public clients using PKCE only.'
        scope:
          type: string
          const: read:content
      required:
      - client_name
      - redirect_uris
  securitySchemes:
    mcpOAuth:
      type: oauth2
      description: 'Optional. Anonymous access to /mcp is fully supported: the five tools published today — search_content, get_article, lookup_angel_number, list_products, get_product — are available on both tiers and return identical data on each. A token raises the rate limit from 30/min per IP to 120/min per client and gives a stable, revocable client identity. Registration is open (RFC 7591) at /mcp/register.'
      flows:
        authorizationCode:
          authorizationUrl: https://www.anahana.com/mcp/authorize
          tokenUrl: https://www.anahana.com/mcp/token
          refreshUrl: https://www.anahana.com/mcp/token
          scopes:
            read:content: Read the public articles and calculators — the same data anonymous callers receive from the same tools.
externalDocs:
  description: Resources for AI Agents — every agent-facing surface with example calls
  url: https://www.anahana.com/en/ai-agents/resources-for-ai-agents/