openapi: 3.2.0
info:
  title: Open Food Facts Authentication API
  version: '1.0'
  description: 'Operations tagged Authentication across 2 of this provider''s published API definitions: open-food-facts-api-v2-openapi.yml, open-food-facts-folksonomy-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- description: dev
  url: https://world.openfoodfacts.net
- description: prod
  url: https://world.openfoodfacts.org
- description: proxy (for doc purpose)
  url: http://localhost:8080
- url: https://api.folksonomy.openfoodfacts.org
  description: Production server
- url: http://localhost:8000
  description: Local development server
tags:
- name: Authentication
  description: Endpoints for user authentication and session management.
paths:
  /cgi/session.pl:
    post:
      summary: Login Session
      operationId: get-cgi-session.pl
      description: Retrieve session cookie for writing operations.
      tags:
      - Authentication
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                user_id:
                  type: string
                  description: 'Username for login


                    Note: you must always use the username (and not the email)

                    as it is far less brittle.

                    '
                password:
                  type: string
                  description: Password for login
                  format: password
              required:
              - user_id
              - password
      responses:
        '200':
          description: Successful login
          headers:
            Set-Cookie:
              schema:
                type: string
                description: Session cookie for subsequent authenticated requests
              examples:
                sessionCookie:
                  value: session=user123&testuser&user_session&abcdef1234567890; domain=.example.net; path=/; SameSite=Lax
        '401':
          description: Authentication failed
      security:
      - userAgentAuth: []
    servers:
    - description: dev
      url: https://world.openfoodfacts.net
    - description: prod
      url: https://world.openfoodfacts.org
    - description: proxy (for doc purpose)
      url: http://localhost:8080
  /auth:
    post:
      tags:
      - Authentication
      summary: Authentication
      description: 'Authentication: provide user/password and get a bearer token in return


        - **username**: Open Food Facts user_id (not email)

        - **password**: user password (clear text, but HTTPS encrypted)


        token is returned, to be used in later requests with usual "Authorization: bearer token" headers'
      operationId: authentication_auth_post
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Body_authentication_auth_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'
    servers:
    - url: https://api.folksonomy.openfoodfacts.org
      description: Production server
    - url: http://localhost:8000
      description: Local development server
  /auth_by_cookie:
    post:
      tags:
      - Authentication
      summary: Authentication By Cookie
      description: 'Authentication: provide Open Food Facts session cookie and get a bearer token in return


        - **session cookie**: Open Food Facts session cookie


        token is returned, to be used in later requests with usual "Authorization: bearer token" headers'
      operationId: authentication_by_cookie_auth_by_cookie_post
      parameters:
      - name: session
        in: cookie
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Session
      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'
    servers:
    - url: https://api.folksonomy.openfoodfacts.org
      description: Production server
    - url: http://localhost:8000
      description: Local development server
components:
  schemas:
    TokenResponse:
      properties:
        access_token:
          type: string
          title: Access Token
        token_type:
          type: string
          title: Token Type
      type: object
      required:
      - access_token
      - token_type
      title: TokenResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    Body_authentication_auth_post:
      properties:
        grant_type:
          anyOf:
          - type: string
            pattern: ^password$
          - type: 'null'
          title: Grant Type
        username:
          type: string
          title: Username
        password:
          type: string
          title: Password
        scope:
          type: string
          title: Scope
          default: ''
        client_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Client Id
        client_secret:
          anyOf:
          - type: string
          - type: 'null'
          title: Client Secret
      type: object
      required:
      - username
      - password
      title: Body_authentication_auth_post
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: session
      description: 'Session cookie containing user ID, username, and session token.

        The value is structured as: user_id&username&user_session&session_token

        e.g. "user_id&exampleuser&user_session&abcdefghijklmnopqrstuvwxyz123456789ABCDEFGHIJKLM".

        The session token is obtained after successful login via the `/cgi/session.pl` endpoint.

        '
    userAgentAuth:
      description: Identification using the User-Agent header. This is recommended in all requests so that we can contact you if there are issues. If we cannot identify the source of problematic API queries, we may have to block them. User-Agent header in the format 'app_name/app_version (URL or contact info)'
      type: apiKey
      in: header
      name: User-Agent
    OAuth2PasswordBearer:
      type: oauth2
      flows:
        password:
          scopes: {}
          tokenUrl: auth
externalDocs:
  description: '**IMPORTANT**: Please read the API introduction before using this API.

    '
  url: https://openfoodfacts.github.io/openfoodfacts-server/api/
x-refined-from:
- open-food-facts-api-v2-openapi.yml
- open-food-facts-folksonomy-openapi.json