Zapier Authentications API

openapi: 3.1.0
info:
  title: Partner Accounts Authentications API
  version: 2024.11.0
  description: '

    ## Introduction


    The Partner API is the best tool for complete style control over a user''s Zapier experience within your app.

    Essentially, it lets you customize how you present Zapier within your product without sacrificing your app''s look,

    feel, and flow.


    Think of it as a native Zapier integration, helping you showcase your best Zapier-powered workflows where it''s most

    helpful to your users (within the flow of your tool). You can customize styling, streamline Zap set-up for users,

    expose relevant Zap information, and more!


    With the Partner API, you can:


    - Get a list of all the apps available in Zapier''s app directory so you can power your app directory and show your

    users all the integration possibilities with your Zapier integration.

    - Have complete style control over how you present Zap templates in your product. The Partner API gives you access

    to the raw Zap Template data so you can give your users access to your Zap template with your product''s style, look

    and feel.

    - Get access to all your Zap templates and give your users the ability to search to quickly find the one they need.

    - Streamline Zap setup by pre-filling fields on behalf of your users.

    - Show users the Zaps they have set up from right within your product keeping them on your site longer and giving them

    complete confidence in their Zapier integration.

    - Embed our Zapier Editor to allow your users to create new Zaps and modify existing ones, without needing to leave

    your product.


    ## Authentication


    There are two ways to authenticate with the Partner API.


    1. Your application''s `client_id` which you will receive once you are approved for access to the API

    (Client ID Authentication)

    2. A user''s access token (Access Token Authentication).


    Which authentication method you should use depends on which endpoint(s) you are using.

    Review each endpoint''s documentation to understand which parameters are required.


    > Note: while we do generate a `client_secret`, the type of grant we use (implicit) doesn''t

    need it so it''s not something we provide.''


    ## Learn more


    See the [Workflow API documentation](https://docs.zapier.com/partner-solutions/workflow-api/intro) for more information.

    '
  contact:
    name: Zapier
    url: https://developer.zapier.com/contact
servers:
- url: https://api.zapier.com
tags:
- name: Authentications
  description: Refers to resources interacting with 'Authentications' associated resources
paths:
  /v2/authentications:
    get:
      operationId: get-authentications
      description: 'Fetch the available Authentications for the provided App. This will only return Authentications that are owned by the user and not those that are shared with them, since it''s not possible to create Zaps with Authentications you don''t own.


        #### When using OAuth


        This endpoint requires the `connection:read` OAuth scope.'
      summary: Zapier Get Authentications
      parameters:
      - in: query
        name: app
        schema:
          type: string
          format: uuid
        description: A canonical App ID, as provided by the `/apps` endpoint.
        required: true
        example: 868f9d3c-2ea0-4f19-a32d-a61b276ab8de
      - in: query
        name: limit
        schema:
          type: integer
        description: Used for paginating results. Specifies the maximum number of items to return per page. If this value is not set, it defaults to 10.
        example: 10
      - in: query
        name: offset
        schema:
          type: integer
        description: Used for paginating results. Specifies the offset to use.
        example: 100
      tags:
      - Authentications
      security:
      - OAuth:
        - connection:read
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationResponse'
              examples:
                AuthenticationsForGoogleSheets:
                  value:
                    links:
                      next: null
                      prev: null
                    meta:
                      count: 1
                      limit: 10
                      offset: 0
                    data:
                    - type: authentication
                      id: example_akLLd8kB
                      app: 81f613aa-c98a-4383-a5fc-195e68647217
                      is_expired: false
                      title: Google Sheets some.user@mycompany.example
                  summary: Authentications for Google Sheets
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Get-authentications403Example:
                  summary: Default get-authentications 403 response
                  x-microcks-default: true
                  value:
                    errors: &id001
                    - {}
          description: 403 Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Get-authentications401Example:
                  summary: Default get-authentications 401 response
                  x-microcks-default: true
                  value:
                    errors: *id001
          description: 401 Response
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Get-authentications409Example:
                  summary: Default get-authentications 409 response
                  x-microcks-default: true
                  value:
                    errors: *id001
          description: 409 Response
        '429':
          headers:
            Retry-After:
              schema:
                type: string
                format: uri
              description: Indicates when to retry the request
            X-RateLimit-Limit:
              schema:
                type: string
                format: uri
              description: The maximum number of requests you're permitted to make per hour.
            X-RateLimit-Remaining:
              schema:
                type: string
                format: uri
              description: The number of requests remaining in the current rate limit window.
            X-RateLimit-Reset:
              schema:
                type: string
                format: uri
              description: The time at which the current rate limit window resets in UTC epoch seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Get-authentications429Example:
                  summary: Default get-authentications 429 response
                  x-microcks-default: true
                  value:
                    errors: *id001
          description: 429 Response
        '503':
          headers:
            Retry-After:
              schema:
                type: string
                format: uri
              description: Indicates when to retry the request
            X-RateLimit-Limit:
              schema:
                type: string
                format: uri
              description: The maximum number of requests you're permitted to make per hour.
            X-RateLimit-Remaining:
              schema:
                type: string
                format: uri
              description: The number of requests remaining in the current rate limit window.
            X-RateLimit-Reset:
              schema:
                type: string
                format: uri
              description: The time at which the current rate limit window resets in UTC epoch seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Get-authentications503Example:
                  summary: Default get-authentications 503 response
                  x-microcks-default: true
                  value:
                    errors: *id001
          description: 503 Response
        '504':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Get-authentications504Example:
                  summary: Default get-authentications 504 response
                  x-microcks-default: true
                  value:
                    errors: *id001
          description: 504 Response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                MalformedRequest.:
                  value:
                    errors:
                    - status: 400
                      code: parse_error
                      title: ParseError
                      detail: Malformed request.
                      source: null
                      meta:
                        source: ZAPIER
                        full_details:
                          message: Malformed request.
                          code: parse_error
                  summary: Malformed request.
          description: This schema can be expected for 4xx 'Malformed request.' errors
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                AServerErrorOccurred.:
                  value:
                    errors:
                    - status: 500
                      code: error
                      title: APIException
                      detail: A server error occurred.
                      source: null
                      meta:
                        source: ZAPIER
                        full_details:
                          message: A server error occurred.
                          code: error
                  summary: A server error occurred.
          description: This schema can be expected for 5xx 'A server error occurred.' errors
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: create-authentication
      description: 'Creates a new Authentication for the provided App. See our Adding an Authentication guide to get started.


        #### When using OAuth


        This endpoint requires the `connection:write` OAuth scope.'
      summary: Zapier Create Authentication
      tags:
      - Authentications
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticationCreateRequest'
            examples:
              NewAuthentication:
                value:
                  data:
                    title: My new auth
                    app: 8cdbc496-c95c-4f19-b3a3-fee03ed5f924
                    authentication_fields:
                      secret: example_E4CrHVvRuxTXrPFLyyZFeRJwJcx2ELQZ
                summary: New Authentication
        required: true
      security:
      - OAuth:
        - connection:write
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationResponse'
              examples:
                CreatedAuth:
                  value:
                    links:
                      next: null
                      prev: null
                    meta:
                      count: 1
                      limit: 1
                      offset: 0
                    data:
                    - type: authentication
                      id: example_DOb4nWkz
                      app: a8aaed31-e257-4479-aaa9-ca02fe2fab04
                      is_expired: false
                      title: 'Example zapier@example.com #5'
                  summary: Created Auth
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Create-authentication403Example:
                  summary: Default create-authentication 403 response
                  x-microcks-default: true
                  value:
                    errors: &id002
                    - {}
          description: 403 Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Create-authentication401Example:
                  summary: Default create-authentication 401 response
                  x-microcks-default: true
                  value:
                    errors: *id002
          description: 401 Response
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Create-authentication409Example:
                  summary: Default create-authentication 409 response
                  x-microcks-default: true
                  value:
                    errors: *id002
          description: 409 Response
        '429':
          headers:
            Retry-After:
              schema:
                type: string
                format: uri
              description: Indicates when to retry the request
            X-RateLimit-Limit:
              schema:
                type: string
                format: uri
              description: The maximum number of requests you're permitted to make per hour.
            X-RateLimit-Remaining:
              schema:
                type: string
                format: uri
              description: The number of requests remaining in the current rate limit window.
            X-RateLimit-Reset:
              schema:
                type: string
                format: uri
              description: The time at which the current rate limit window resets in UTC epoch seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Create-authentication429Example:
                  summary: Default create-authentication 429 response
                  x-microcks-default: true
                  value:
                    errors: *id002
          description: 429 Response
        '503':
          headers:
            Retry-After:
              schema:
                type: string
                format: uri
              description: Indicates when to retry the request
            X-RateLimit-Limit:
              schema:
                type: string
                format: uri
              description: The maximum number of requests you're permitted to make per hour.
            X-RateLimit-Remaining:
              schema:
                type: string
                format: uri
              description: The number of requests remaining in the current rate limit window.
            X-RateLimit-Reset:
              schema:
                type: string
                format: uri
              description: The time at which the current rate limit window resets in UTC epoch seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Create-authentication503Example:
                  summary: Default create-authentication 503 response
                  x-microcks-default: true
                  value:
                    errors: *id002
          description: 503 Response
        '504':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Create-authentication504Example:
                  summary: Default create-authentication 504 response
                  x-microcks-default: true
                  value:
                    errors: *id002
          description: 504 Response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                MalformedRequest.:
                  value:
                    errors:
                    - status: 400
                      code: parse_error
                      title: ParseError
                      detail: Malformed request.
                      source: null
                      meta:
                        source: ZAPIER
                        full_details:
                          message: Malformed request.
                          code: parse_error
                  summary: Malformed request.
          description: This schema can be expected for 4xx 'Malformed request.' errors
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                AServerErrorOccurred.:
                  value:
                    errors:
                    - status: 500
                      code: error
                      title: APIException
                      detail: A server error occurred.
                      source: null
                      meta:
                        source: ZAPIER
                        full_details:
                          message: A server error occurred.
                          code: error
                  summary: A server error occurred.
          description: This schema can be expected for 5xx 'A server error occurred.' errors
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    AppsImages:
      type: object
      description: Images/icons of various resolutions to represent the app.
      properties:
        url_16x16:
          type: string
          description: 16x16 resolution image URL
          example: example-value
        url_32x32:
          type: string
          description: 32x32 resolution image URL
          example: example-value
        url_64x64:
          type: string
          description: 64x64 resolution image URL
          example: example-value
        url_128x128:
          type: string
          description: 128x128 resolution image URL
          example: example-value
      required:
      - url_128x128
      - url_16x16
      - url_32x32
      - url_64x64
    _AuthenticationCreateRequest:
      type: object
      description: The object used to create a new Authentication
      properties:
        title:
          type: string
          description: The title of the authentication.
          maxLength: 255
          example: Example Name
        app:
          type: string
          format: uuid
          description: A canonical App ID, as provided by the `/apps` endpoint.
          example: 550e8400-e29b-41d4-a716-446655440000
        authentication_fields:
          type: object
          additionalProperties: {}
          description: Required values to create an authentication. These values will be used by the target integration to successfully create the Authentication. See our Adding an Authentication guide for more information.
          example: {}
      required:
      - app
      - authentication_fields
      - title
    AuthenticationCreateRequest:
      type: object
      description: Inputs to create a new Authentication
      properties:
        data:
          $ref: '#/components/schemas/_AuthenticationCreateRequest'
      required:
      - data
    AuthenticationResponse:
      type: object
      description: 'Base Response definition to be used in other Response Serializers.


        Be sure to include the `data` field after using this class'
      properties:
        links:
          allOf:
          - $ref: '#/components/schemas/Links'
          description: The links object returned in paginated response bodies.
          example: example-value
        meta:
          allOf:
          - $ref: '#/components/schemas/BaseMeta'
          description: The meta object returned in paginated response bodies.
          example: example-value
        data:
          type: array
          items:
            $ref: '#/components/schemas/Authentication'
          description: The Authentications present, provided they exist
          example:
          - {}
      required:
      - links
      - meta
    Error:
      type: object
      description: Base Error definition
      properties:
        status:
          type: integer
          description: The HTTP status code applicable to this problem.
          example: 100
        code:
          type: string
          description: A unique identifier for this particular occurrence of the problem.
          example: example-value
        title:
          type: string
          description: A short summary of the problem.
          example: Example Name
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
          example: example-value
        source:
          oneOf:
          - $ref: '#/components/schemas/ErrorSource'
          - type: 'null'
          description: An object containing references to the primary source of the error.
          example: example-value
        meta:
          type:
          - object
          - 'null'
          additionalProperties: {}
          description: Freeform metadata about the error
          example: {}
    Apps:
      type: object
      description: An app that integrates with Zapier
      properties:
        id:
          type: string
          description: Unique id of the app
          example: '500123'
        type:
          type: string
          default: app
          description: The type of this object.
          example: app
        image:
          type: string
          description: Default image/icon to represent the app.
          example: example-value
        links:
          type: object
          additionalProperties: {}
          description: "A url that, when visited, will direct the user to authenticate with the app and allow Zapier access to the app, thus creating a new Authentication.\n\n            If value is `null`, then no authentication is required to use the app. Client ID-authenticated requests will never have this object's fields populated."
          example: {}
        action_types:
          type: array
          items: {}
          description: A list of action types for this specific App
          example:
          - standard
        title:
          type: string
          description: Human readable name of the app
          example: Example Name
        images:
          allOf:
          - $ref: '#/components/schemas/AppsImages'
          description: The URL of images (of various sizes) for this specific App
          example: example-value
        hex_color:
          type: string
          description: A branded color that can be used to represent the app.
          example: example-value
        categories:
          type: array
          items:
            $ref: '#/components/schemas/Category'
          description: A list of categories to which this app belongs. Helpful in identifying apps by type and functionality.
          example:
          - {}
        description:
          type: string
          description: Human readable description of the app.
          example: Example description for this resource.
      required:
      - action_types
      - categories
      - description
      - hex_color
      - id
      - image
      - images
      - links
      - title
    Category:
      type: object
      description: Category an app belongs to.
      properties:
        slug:
          type: string
          description: The shortened slug name for this category
          example: example-value
      required:
      - slug
    BaseMeta:
      type: object
      description: The meta object returned in paginated response bodies.
      properties:
        count:
          type: integer
          minimum: 0
          description: The total number of objects in the collection represented by the endpoint.
          example: 100
        limit:
          type:
          - integer
          - 'null'
          minimum: 1
          description: The limit value used in the request.
          example: 100
        offset:
          type: integer
          minimum: 0
          default: 0
          description: The offset value used in the request.
          example: 0
      required:
      - count
      - limit
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: An array of error objects.
          example:
          - {}
      required:
      - errors
    Links:
      type: object
      description: The links object returned in paginated response bodies.
      properties:
        next:
          type:
          - string
          - 'null'
          description: The URL of the next page of paginated results.
          example: example-value
        prev:
          type:
          - string
          - 'null'
          description: The URL of the previous page of paginated results.
          example: example-value
    AuthenticationTypeEnum:
      enum:
      - authentication
      type: string
      description: '* `authentication` - authentication'
    ErrorSource:
      type: object
      description: Populates the `source` object inside our error responses.
      properties:
        pointer:
          type: string
          description: Pointer to the value in the request document that caused the error e.g. `/actions`.
          example: example-value
        parameter:
          type: string
          description: A string indicating which URI query parameter caused the error.
          example: example-value
        header:
          type: string
          description: A string indicating the name of a single request header which caused the error.
          example: example-value
    Authentication:
      type: object
      description: 'An Authentication contains various fields, often credentials such as API tokens, used to access Partner APIs on

        behalf of a user. The actual fields are held securely by Zapier'
      properties:
        type:
          allOf:
          - $ref: '#/components/schemas/AuthenticationTypeEnum'
          readOnly: true
          default: authentication
          description: 'The type of this object.


            * `authentication` - authentication'
          example: authentication
        id:
          type: string
          description: The identifier for this specific Authentication
          example: '500123'
        app:
          description: An app that integrates with Zapier.
          oneOf:
          - $ref: '#/components/schemas/Apps'
          - type: string
          example: example-value
        is_expired:
          type: boolean
          description: If `true`, this Authentication has expired. It will not be usable, and the user needs to be directed to reconnect it.
          example: true
        title:
          type: string
          description: The title of this specific Authentication
          example: Example Name
      required:
      - app
      - id
      - is_expired
      - title
      - type
  securitySchemes:
    ClientIDAuthentication:
      type: apiKey
      in: query
      name: client_id
      description: See our authentication documentation for how to find your Client ID
      x-zapier-auth-scheme-exempt: true
    OAuth:
      type: oauth2
      description: 'See our OAuth2 authentication documentation here: https://docs.zapier.com/powered-by-zapier/api-reference/authentication'
      flows:
        authorizationCode:
          authorizationUrl: https://zapier.com/oauth/authorize/
          tokenUrl: https://zapier.com/oauth/token/
          refreshUrl: https://zapier.com/oauth/token/
          scopes:
            profile: Read profile information about the currently-authenticated user
            zap: Read Zaps
            zap:write: Write Zaps
            authentication: Read Authentications
            authentication:write: Write Authentications
            zap:runs: Read Zap Runs
            action:run: Run an Action
            zap:all: Read Zaps accessible to the account
        implicit:
          authorizationUrl: https://zapier.com/oauth/authorize/
          scopes:
            profile: Read profile information about the currently-authenticated user
            zap: Read Zaps
            zap:write: Write Zaps
            authentication: Read Authentications
            authentication:write: Write Authentications
            zap:runs: Read Zap Runs
            action:run: Run an Action
            zap:all: Read Zaps accessible to the account