Émile OAuth API

openapi: 3.2.0
info:
  title: Émile OAuth API
  description: '# Émile API


    Public API for the Émile wine cellar app.


    ## Authentication


    Two methods are supported:


    **1. API Key** (recommended for external clients: MCP servers, scripts, ChatGPT custom connectors)


    Send your key in the `X-API-Key` header OR as `Authorization: Bearer emile_live_...`.


    Generate keys from your iOS app: **Profil → Paramètres → Clés API**.


    **2. Supabase JWT** (used by the official iOS app — internal)


    Send `Authorization: Bearer `.


    ## Rate Limits


    All endpoints are rate-limited per user. See each endpoint''s documentation for specific limits.

    On exceeded: HTTP 429 with `Retry-After` header and `X-RateLimit-*` informational headers.


    | Endpoint | Limit |

    |---|---|

    | `POST /scan` | 10/min, 50/day |

    | `POST /me/scan:batch` | 5/hour |

    | `POST /recommendations` | 20/min, 100/day |

    | `POST /cellars/{id}/bottles` | 60/min, 500/day |

    | `POST /me/bottles:batch` | 10/hour, 50/day |

    | `POST /me/keys` | 5/hour, 20/day |'
  version: '1.0'
tags:
- name: OAuth
paths:
  /oauth/authorize:
    get:
      tags:
      - OAuth
      summary: Authorize
      description: 'Validates the OAuth request shape, then 302-redirects to the

        consent UI which lives on app.emile.wine. Errors that occur BEFORE

        redirect_uri validation return a direct 400 (never redirect to an

        untrusted client URL — RFC 6749 § 4.1.2.1).'
      operationId: authorize_oauth_authorize_get
      parameters:
      - name: client_id
        in: query
        required: true
        schema:
          type: string
          title: Client Id
      - name: redirect_uri
        in: query
        required: true
        schema:
          type: string
          title: Redirect Uri
      - name: response_type
        in: query
        required: false
        schema:
          type: string
          default: code
          title: Response Type
      - name: scope
        in: query
        required: false
        schema:
          type: string
          default: emile.full
          title: Scope
      - name: state
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: State
      - name: code_challenge
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Code Challenge
      - name: code_challenge_method
        in: query
        required: false
        schema:
          type: string
          default: S256
          title: Code Challenge Method
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /oauth/authorize/grant:
    post:
      tags:
      - OAuth
      summary: Authorize Grant
      description: 'Called by the consent UI after the user clicks "Autoriser". The

        Supabase JWT identifies which user is granting consent. Returns the

        redirect URL with the freshly-issued code.'
      operationId: authorize_grant_oauth_authorize_grant_post
      security:
      - HTTPBearer: []
      parameters:
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GrantRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrantResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /oauth/token:
    post:
      tags:
      - OAuth
      summary: Token
      operationId: token_oauth_token_post
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Body_token_oauth_token_post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /oauth/revoke:
    post:
      tags:
      - OAuth
      summary: Revoke
      description: 'Idempotent. RFC 7009 § 2.2: even unknown tokens return 200. We

        still authenticate the client to prevent unauthenticated DoS of

        other people''s tokens (though the impact would be 0 since revoking

        is idempotent — we just rate-limit anyway).'
      operationId: revoke_oauth_revoke_post
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Body_revoke_oauth_revoke_post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /oauth/introspect:
    post:
      tags:
      - OAuth
      summary: Introspect
      description: 'Resolves an access token to its claims for the MCP remote

        server. Protected by a shared secret (env `OAUTH_INTROSPECT_SECRET`)

        rather than client_credentials because the introspector is our own

        internal service, not an OAuth client.'
      operationId: introspect_oauth_introspect_post
      parameters:
      - name: X-Introspect-Secret
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Introspect-Secret
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Body_introspect_oauth_introspect_post'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntrospectionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /oauth/clients/{client_id}:
    get:
      tags:
      - OAuth
      summary: Get Client Public
      description: 'Consent UI calls this (no auth) to know what name/logo to show.

        Client names + logos are public by nature — they appear in the

        consent screen everyone sees.'
      operationId: get_client_public_oauth_clients__client_id__get
      parameters:
      - name: client_id
        in: path
        required: true
        schema:
          type: string
          title: Client Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientPublicResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /oauth/register:
    post:
      tags:
      - OAuth
      summary: Register
      description: 'Dynamic Client Registration — RFC 7591. Unauthenticated by

        design (stores need to register themselves without a pre-existing

        account on Émile), tightly rate-limited (5/h per IP) to avoid

        drive-by client spam.


        All clients created here are public (`is_dynamic=true`, no secret)

        — they must use PKCE for the auth code exchange. Confidential

        clients are still possible but are curated by an admin via the

        DB directly (no public endpoint exposes them).'
      operationId: register_oauth_register_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /.well-known/oauth-authorization-server:
    get:
      tags:
      - OAuth
      summary: Oauth Authorization Server Metadata
      description: 'RFC 8414 — Authorization Server Metadata. Stores hit this URL

        during onboarding to learn our endpoints, grant types, scopes,

        and PKCE support.'
      operationId: oauth_authorization_server_metadata__well_known_oauth_authorization_server_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /.well-known/oauth-protected-resource:
    get:
      tags:
      - OAuth
      summary: Oauth Protected Resource Metadata
      description: 'RFC 9728 — Protected Resource Metadata. Tells MCP clients

        which authorization server protects this resource. Once the MCP

        remote container lives at mcp.emile.wine (Phase C5) it will host

        its OWN copy of this endpoint pointing back at api.emile.wine

        as the authorization server.'
      operationId: oauth_protected_resource_metadata__well_known_oauth_protected_resource_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
components:
  schemas:
    GrantResponse:
      properties:
        redirect_to:
          type: string
          title: Redirect To
      type: object
      required:
      - redirect_to
      title: GrantResponse
      description: 'Returned to the consent UI''s fetch() call. The browser then

        does `window.location = redirect_to` to bounce back to the store.

        Server-side redirect would also work but it requires the consent

        UI to be on the same origin, which it isn''t.'
    Body_token_oauth_token_post:
      properties:
        grant_type:
          type: string
          title: Grant Type
        client_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Client Id
        client_secret:
          anyOf:
          - type: string
          - type: 'null'
          title: Client Secret
        code:
          anyOf:
          - type: string
          - type: 'null'
          title: Code
        redirect_uri:
          anyOf:
          - type: string
          - type: 'null'
          title: Redirect Uri
        code_verifier:
          anyOf:
          - type: string
          - type: 'null'
          title: Code Verifier
        refresh_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Refresh Token
      type: object
      required:
      - grant_type
      title: Body_token_oauth_token_post
    ClientPublicResponse:
      properties:
        client_id:
          type: string
          title: Client Id
        name:
          type: string
          title: Name
        logo_uri:
          anyOf:
          - type: string
          - type: 'null'
          title: Logo Uri
        scope_description:
          type: string
          title: Scope Description
          default: Accès complet à ta cave Émile (lecture + écriture)
      type: object
      required:
      - client_id
      - name
      title: ClientPublicResponse
    IntrospectionResponse:
      properties:
        active:
          type: boolean
          title: Active
        user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: User Id
        client_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Client Id
        scope:
          anyOf:
          - type: string
          - type: 'null'
          title: Scope
        exp:
          anyOf:
          - type: integer
          - type: 'null'
          title: Exp
          description: Unix epoch seconds
      type: object
      required:
      - active
      title: IntrospectionResponse
    RegisterResponse:
      properties:
        client_id:
          type: string
          title: Client Id
        client_secret:
          anyOf:
          - type: string
          - type: 'null'
          title: Client Secret
        client_id_issued_at:
          type: integer
          title: Client Id Issued At
        client_secret_expires_at:
          type: integer
          title: Client Secret Expires At
          default: 0
        client_name:
          type: string
          title: Client Name
        redirect_uris:
          items:
            type: string
          type: array
          title: Redirect Uris
        grant_types:
          items:
            type: string
          type: array
          title: Grant Types
        response_types:
          items:
            type: string
          type: array
          title: Response Types
        scope:
          type: string
          title: Scope
        logo_uri:
          anyOf:
          - type: string
          - type: 'null'
          title: Logo Uri
        token_endpoint_auth_method:
          type: string
          title: Token Endpoint Auth Method
          default: client_secret_post
      type: object
      required:
      - client_id
      - client_id_issued_at
      - client_name
      - redirect_uris
      - grant_types
      - response_types
      - scope
      title: RegisterResponse
      description: 'RFC 7591 § 3.2.1. `client_secret_expires_at = 0` means it

        never expires; the field is mandatory when a secret is returned.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Body_revoke_oauth_revoke_post:
      properties:
        token:
          type: string
          title: Token
        token_type_hint:
          anyOf:
          - type: string
          - type: 'null'
          title: Token Type Hint
        client_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Client Id
        client_secret:
          anyOf:
          - type: string
          - type: 'null'
          title: Client Secret
      type: object
      required:
      - token
      title: Body_revoke_oauth_revoke_post
    TokenResponse:
      properties:
        access_token:
          type: string
          title: Access Token
        token_type:
          type: string
          title: Token Type
          default: Bearer
        expires_in:
          type: integer
          title: Expires In
        refresh_token:
          type: string
          title: Refresh Token
        scope:
          type: string
          title: Scope
      type: object
      required:
      - access_token
      - expires_in
      - refresh_token
      - scope
      title: TokenResponse
    GrantRequest:
      properties:
        client_id:
          type: string
          title: Client Id
        redirect_uri:
          type: string
          title: Redirect Uri
        scope:
          type: string
          title: Scope
          default: emile.full
        state:
          anyOf:
          - type: string
          - type: 'null'
          title: State
        code_challenge:
          anyOf:
          - type: string
          - type: 'null'
          title: Code Challenge
        code_challenge_method:
          anyOf:
          - type: string
          - type: 'null'
          title: Code Challenge Method
          default: S256
      type: object
      required:
      - client_id
      - redirect_uri
      title: GrantRequest
    Body_introspect_oauth_introspect_post:
      properties:
        token:
          type: string
          title: Token
      type: object
      required:
      - token
      title: Body_introspect_oauth_introspect_post
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    RegisterRequest:
      properties:
        client_name:
          type: string
          maxLength: 120
          minLength: 1
          title: Client Name
        redirect_uris:
          items:
            type: string
          type: array
          maxItems: 10
          minItems: 1
          title: Redirect Uris
        grant_types:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Grant Types
        response_types:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Response Types
        scope:
          anyOf:
          - type: string
          - type: 'null'
          title: Scope
        logo_uri:
          anyOf:
          - type: string
            maxLength: 2048
          - type: 'null'
          title: Logo Uri
      type: object
      required:
      - client_name
      - redirect_uris
      title: RegisterRequest
      description: 'RFC 7591 § 2 — a subset of the client metadata fields. The

        spec allows many more (jwks, contacts, tos_uri, …) — we accept

        them silently but only persist what we know how to handle, so

        aware stores remain conformant.'
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer