openapi: 3.2.0
info:
  title: Wazo Google API
  version: '0.1'
  contact:
    name: Wazo Dev Team
    url: https://wazo-platform.org/
    email: dev@wazo.community
  x-logo:
    url: https://wazo-platform.org/images/logo-black.svg
    backgroundColor: '#FAFAFA'
    altText: Wazo Logo
  description: 'Operations tagged google across 2 of this provider''s published API definitions: wazo-auth-api-openapi.yml, wazo-dird-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: /0.1
tags:
- name: google
paths:
  /users/{user_uuid}/external/google:
    get:
      summary: Get a Google token
      description: '**Required ACL**: `auth.users.{user_uuid}.external.google.read`'
      tags:
      - google
      parameters:
      - $ref: '#/components/parameters/user_uuid'
      responses:
        '200':
          description: The auth data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleGetResult'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
    post:
      summary: Ask for a verification URL and store code to get token
      description: '**Required ACL**: `auth.users.{user_uuid}.external.google.create`.


        More info on Google permissions: https://developers.google.com/identity/protocols/googlescopes"

        '
      tags:
      - google
      parameters:
      - $ref: '#/components/parameters/user_uuid'
      responses:
        '201':
          description: Authentication url
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GooglePostResult'
        '400':
          description: Invalid body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GooglePost'
    delete:
      summary: Delete a Google token
      description: '**Required ACL**: `auth.users.{user_uuid}.external.google.delete`'
      tags:
      - google
      parameters:
      - $ref: '#/components/parameters/user_uuid'
      responses:
        '204':
          description: External authentication deleted
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
    servers:
    - url: /0.1
  /backends/google/sources/{source_uuid}/contacts:
    get:
      description: '**Required ACL:** `dird.backends.google.sources.{source_uuid}.contacts.read`'
      operationId: list_google_contacts_from_source
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      - in: path
        name: source_uuid
        required: true
        description: Source uuid
        schema:
          type: string
      - $ref: '#/components/parameters/order'
      - $ref: '#/components/parameters/direction'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/search'
      summary: Retrieve all contacts from `google`
      tags:
      - google
      responses:
        '200':
          description: 'Contacts as fetched from Google API and transformed to match the dird internals


            Note that the total in the result is always the total matching for the current query.

            Which is the same as the filtered value, this is a limitation of the Google API.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleContactList'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyError'
        '404':
          description: No such source
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyError'
        '503':
          description: Another service is unavailable (e.g. wazo-auth, google, ...)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyError'
      security:
      - wazo_auth_token: []
    servers:
    - url: /0.1
  /backends/google/sources:
    get:
      operationId: list_google_source
      summary: Get google configuration
      description: '**Required ACL:** `dird.backends.google.sources.read`'
      tags:
      - google
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      - $ref: '#/components/parameters/recurse'
      - $ref: '#/components/parameters/order'
      - $ref: '#/components/parameters/direction'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Configured google source
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleSourceItems'
      security:
      - wazo_auth_token: []
    post:
      operationId: create_google_source
      summary: Configure a source for the google backend
      description: '**Required ACL:** `dird.backends.google.sources.create`


        This resource configures a Google source for wazo-dird. Columns that are available from this source

        are:


        * name: the contact name

        * numbers: a list of phone numbers

        * numbers_by_label: a map of type to numbers {''mobile'': <number>, ''home'': <number>, ...}. Types are defined by Google, currently known types include: ''home'', ''work'', ''mobile'', ''other'', ''main'', ''home_fax'', ''work_fax'', ''google_voice'', ''pager''.

        * numbers_except_label: a map from type to every other number {''mobile'': [<number>, <number], ''home'': [<number>, <number>], ...}. See available types above. For example, the ''mobile'' key will contain the ''work'' and ''home'' numbers, but will exclude the ''mobile'' number.

        * emails: a list of email addresses

        '
      tags:
      - google
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      responses:
        '201':
          description: The created display
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleSource'
              example:
                auth:
                  host: localhost
                  port: 80
                  prefix: /api/auth
                  https: false
                  version: 0.1
                format_columns:
                  phone: '{numbers[0]}'
                  phone_mobile: '{numbers_by_label[mobile]}'
                  reverse: '{name}'
                  email: '{emails[0]}'
                name: google
                first_matched_columns:
                - numbers
                searched_columns:
                - numbers
                - emails
                - name
        '400':
          $ref: '#/components/responses/CreateError'
        '409':
          description: Source already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleSource'
        description: The display configuration body
        required: true
      security:
      - wazo_auth_token: []
    servers:
    - url: /0.1
  /backends/google/sources/{source_uuid}:
    get:
      operationId: get_a_google_source
      summary: Get a `google` source configuration
      description: '**Required ACL:** `dird.backends.google.sources.{source_uuid}.read`'
      tags:
      - google
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      - $ref: '#/components/parameters/sourceuuid'
      responses:
        '200':
          description: The `google` source
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleSource'
        '404':
          $ref: '#/components/responses/NotFoundError'
      security:
      - wazo_auth_token: []
    put:
      operationId: update_google_source
      summary: Update a `google` source configuration
      description: '**Required ACL:** `dird.backends.google.sources.{source_uuid}.update`'
      tags:
      - google
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      - $ref: '#/components/parameters/sourceuuid'
      responses:
        '204':
          $ref: '#/components/responses/ResourceUpdated'
        '400':
          $ref: '#/components/responses/UpdateError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          description: Duplicate Source
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleSource'
        description: The source configuration body
        required: true
      security:
      - wazo_auth_token: []
    delete:
      operationId: delete_google_source
      summary: Delete a `google` source configuration
      description: '**Required ACL:** `dird.backends.google.sources.{source_uuid}.delete`'
      tags:
      - google
      parameters:
      - $ref: '#/components/parameters/tenantuuid'
      - $ref: '#/components/parameters/sourceuuid'
      responses:
        '204':
          $ref: '#/components/responses/ResourceDeleted'
        '404':
          $ref: '#/components/responses/NotFoundError'
      security:
      - wazo_auth_token: []
    servers:
    - url: /0.1
components:
  schemas:
    GooglePostResult:
      type: object
      required:
      - verification_url
      properties:
        verification_url:
          type: string
          description: The URL to confirm the authorization
    APIError:
      type: object
      properties:
        timestamp:
          type: number
        message:
          type: string
        resource:
          type: string
        details:
          type: object
    GoogleGetResult:
      type: object
      properties:
        access_token:
          type: string
          description: Google token
        scope:
          type: string
          description: Scope permissions given to the `access token`
        token_expiration:
          type: integer
          description: Token expiration
      required:
      - access_token
      - scope
      - token_expiration
    GooglePost:
      type: object
      properties:
        scope:
          description: Scope permissions requested
          type: array
          items:
            type: string
          default:
          - https://www.googleapis.com/auth/userinfo.profile
          - https://www.googleapis.com/auth/contacts
    LegacyError:
      title: LegacyError
      description: Error message for the client
      properties:
        timestamp:
          description: Time at which the error occured
          type: array
          items:
            type: number
            format: timestamp
        reason:
          description: Human readable explanation of the error
          type: array
          items:
            type: string
        status_code:
          description: HTTP status code
          type: integer
    SourceItems:
      properties:
        total:
          type: integer
          description: The number of configured sources for this backend
          readOnly: true
        filtered:
          type: integer
          description: The number of configured sources matching the searched terms for this backend
          readOnly: true
    WazoAuthConfigNoAuth:
      title: Auth
      allOf:
      - $ref: '#/components/schemas/ExternalServiceConfig'
      - properties:
          port:
            type: integer
            default: 80
          version:
            type: string
            default: '0.1'
    GoogleSourceItems:
      title: GoogleSourceItems
      allOf:
      - $ref: '#/components/schemas/SourceItems'
      - properties:
          items:
            type: array
            items:
              $ref: '#/components/schemas/GoogleSource'
            readOnly: true
      - required:
        - items
        - total
        - filtered
    ExternalServiceConfig:
      properties:
        host:
          type: string
          default: localhost
        verify_certificate:
          type: string
          description: If the HTTPs certificates should be verified and the path of the certificate if a custom certificate is used.
          default: 'true'
        timeout:
          type: number
    GoogleContactList:
      properties:
        items:
          type: array
          items:
            type: object
          readOnly: true
        total:
          type: integer
          description: The number of contacts matching the searched terms
          readOnly: true
        filtered:
          type: integer
          description: The number of contacts matching the searched terms
          readOnly: true
    GoogleSource:
      title: GoogleSource
      allOf:
      - $ref: '#/components/schemas/Source'
      - properties:
          auth:
            $ref: '#/components/schemas/WazoAuthConfigNoAuth'
      - required:
        - name
        - auth
    Source:
      properties:
        uuid:
          type: string
          description: The source's UUID
          readOnly: true
        name:
          type: string
          description: The source's name
        searched_columns:
          type: array
          items:
            type: string
            description: A list of columns which should be searched when doing a look up
        first_matched_columns:
          type: array
          items:
            type: string
          description: A list of columns which should be searched when doing a reverse look up
        format_columns:
          type: object
          description: A mapping of new fields and a python format string to generate the new columns value
  parameters:
    user_uuid:
      name: user_uuid
      in: path
      description: The UUID of the user
      required: true
      schema:
        type: string
    tenantuuid:
      name: Wazo-Tenant
      in: header
      description: The tenant's UUID, defining the ownership of a given resource.
      required: false
      schema:
        type: string
    Offset:
      name: offset
      in: query
      description: The offset defines the number of items of the collection to skip
      required: false
      schema:
        type: integer
        default: 0
    offset:
      name: offset
      in: query
      description: The offset defines the offsets the start by the number specified
      required: false
      schema:
        type: integer
        default: 0
    order:
      required: false
      name: order
      in: query
      description: Name of the field to use for sorting the list of items returned.
      schema:
        type: string
    Limit:
      name: limit
      in: query
      description: The limit defines the number of individual objects that are returned
      required: false
      schema:
        type: integer
    direction:
      required: false
      name: direction
      in: query
      description: Sort list of items in 'asc' (ascending) or 'desc' (descending) order
      schema:
        type: string
        enum:
        - asc
        - desc
    recurse:
      name: recurse
      in: query
      description: Should the query include sub-tenants
      required: false
      schema:
        type: boolean
        default: false
    sourceuuid:
      name: source_uuid
      in: path
      description: The source's UUID
      required: true
      schema:
        type: string
    search:
      required: false
      name: search
      in: query
      description: Search term for filtering a list of items. Only items with a field containing the search term will be returned.
      schema:
        type: string
    limit:
      name: limit
      in: query
      description: The limit defines the number of individual objects that are returned
      required: false
      schema:
        type: integer
  responses:
    NotFoundError:
      description: The resource requested was not found on the server
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
    ResourceDeleted:
      description: Resource was deleted successfully
    ResourceUpdated:
      description: Resource was updated successfully
    CreateError:
      description: An error occurred when creating the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
    UpdateError:
      description: An error occurred when updating the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
  securitySchemes:
    wazo_auth_basic:
      type: http
      scheme: basic
    wazo_auth_token:
      type: apiKey
      name: X-Auth-Token
      in: header
x-refined-from:
- wazo-auth-api-openapi.yml
- wazo-dird-api-openapi.yml
x-xivo-name: agentd
x-xivo-port: 9493
x-apievangelist-source:
  harvested_from: https://github.com/wazo-platform/wazo-agentd
  assembly: base plugin api.yml deep-merged with all plugin api.yml fragments, reproducing what the running service serves at /api/agentd/1.0/api/api.yml (see wazo_agentd/plugins/api/http.py — xivo.chain_map.ChainMap)
  spec_version: Swagger 2.0 (as published by Wazo)
  harvested: '2026-08-17'