openapi: 3.0.4
info:
  title: Custom Integration Access Lifecycle API
  description: >-
    You can define a custom resource for integrations not natively supported by
    P0. To start provisioning access for your custom resource with P0, you have
    to implement the endpoints defined in this API and configure a custom
    resource in the P0 console that refers to your endpoints.


    This OpenAPI specification is licensed under the Apache License, Version
    2.0.

    It is intended solely for the purpose of enabling systems to interoperate
    with P0 Security’s services. 

    Use of this specification does not imply any partnership, endorsement, or
    affiliation with P0 Security. By using this specification, you agree to
    abide by the license terms and avoid misrepresenting its origin.
  termsOfService: https://p0.app/tos
  contact:
    email: support@p0.dev
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 0.0.1
  x-gitbook-description-document:
    object: document
    data:
      schemaVersion: 8
    nodes:
      - object: block
        type: paragraph
        isVoid: false
        data: {}
        nodes:
          - object: text
            leaves:
              - object: leaf
                text: >-
                  You can define a custom resource for integrations not natively
                  supported by P0. To start provisioning access for your custom
                  resource with P0, you have to implement the endpoints defined
                  in this API and configure a custom resource in the P0 console
                  that refers to your endpoints.
                marks: []
      - object: block
        type: paragraph
        isVoid: false
        data: {}
        nodes:
          - object: text
            leaves:
              - object: leaf
                text: >-
                  This OpenAPI specification is licensed under the Apache
                  License, Version 2.0.

                  It is intended solely for the purpose of enabling systems to
                  interoperate with P0 Security’s services.

                  Use of this specification does not imply any partnership,
                  endorsement, or affiliation with P0 Security. By using this
                  specification, you agree to abide by the license terms and
                  avoid misrepresenting its origin.
                marks: []
  x-gitbook-description-html: >-
    <p>You can define a custom resource for integrations not natively supported
    by P0. To start provisioning access for your custom resource with P0, you
    have to implement the endpoints defined in this API and configure a custom
    resource in the P0 console that refers to your endpoints.</p><p>This OpenAPI
    specification is licensed under the Apache License, Version 2.0.<br>It is
    intended solely for the purpose of enabling systems to interoperate with P0
    Security’s services.<br>Use of this specification does not imply any
    partnership, endorsement, or affiliation with P0 Security. By using this
    specification, you agree to abide by the license terms and avoid
    misrepresenting its origin.</p>
externalDocs:
  description: Learn more about P0 Security
  url: https://p0.dev
  x-gitbook-description-html: <p>Learn more about P0 Security</p>
tags:
  - name: grant
    description: Grant access to your resources
    x-gitbook-description-document:
      object: document
      data:
        schemaVersion: 8
      nodes:
        - object: block
          type: paragraph
          isVoid: false
          data: {}
          nodes:
            - object: text
              leaves:
                - object: leaf
                  text: Grant access to your resources
                  marks: []
    x-gitbook-description-html: <p>Grant access to your resources</p>
  - name: revoke
    description: Revoke access from your resources
    x-gitbook-description-document:
      object: document
      data:
        schemaVersion: 8
      nodes:
        - object: block
          type: paragraph
          isVoid: false
          data: {}
          nodes:
            - object: text
              leaves:
                - object: leaf
                  text: Revoke access from your resources
                  marks: []
    x-gitbook-description-html: <p>Revoke access from your resources</p>
  - name: list
    description: List resources that are available for requesting
    x-gitbook-description-document:
      object: document
      data:
        schemaVersion: 8
      nodes:
        - object: block
          type: paragraph
          isVoid: false
          data: {}
          nodes:
            - object: text
              leaves:
                - object: leaf
                  text: List resources that are available for requesting
                  marks: []
    x-gitbook-description-html: <p>List resources that are available for requesting</p>
paths:
  /access/{accessType}/grant:
    post:
      tags:
        - grant
      summary: Grant access
      description: Grant a user access to a resource
      operationId: grantRequest
      parameters:
        - name: accessType
          in: path
          description: >-
            The type of access requested. The access type is configured during
            setup of the custom resource in P0.
          required: true
          schema:
            type: string
          x-gitbook-description-html: >-
            <p>The type of access requested. The access type is configured
            during setup of the custom resource in P0.</p>
      requestBody:
        description: Grant a user access to a resource
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PermissionRequest"
        required: true
        x-gitbook-description-html: <p>Grant a user access to a resource</p>
      responses:
        "200":
          $ref: "#/components/responses/EmptySuccessResponse"
        "201":
          $ref: "#/components/responses/EmptySuccessResponse"
        "202":
          $ref: "#/components/responses/EmptySuccessResponse"
        default:
          $ref: "#/components/responses/ErrorResponse"
      security:
        - bearerAuth: []
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 8
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: Grant a user access to a resource
                    marks: []
      x-gitbook-description-html: <p>Grant a user access to a resource</p>
  /access/{accessType}/revoke:
    post:
      tags:
        - revoke
      summary: Revoke access
      description: Revoke a user access from a resource
      operationId: revokeRequest
      parameters:
        - name: accessType
          in: path
          description: >-
            The type of access requested. The access type is configured during
            setup of the custom resource in P0.
          required: true
          schema:
            type: string
          x-gitbook-description-html: >-
            <p>The type of access requested. The access type is configured
            during setup of the custom resource in P0.</p>
      requestBody:
        description: Revoke a user access from a resource
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PermissionRequest"
        required: true
        x-gitbook-description-html: <p>Revoke a user access from a resource</p>
      responses:
        "200":
          $ref: "#/components/responses/EmptySuccessResponse"
        "201":
          $ref: "#/components/responses/EmptySuccessResponse"
        "202":
          $ref: "#/components/responses/EmptySuccessResponse"
        default:
          $ref: "#/components/responses/ErrorResponse"
      security:
        - bearerAuth: []
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 8
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: Revoke a user access from a resource
                    marks: []
      x-gitbook-description-html: <p>Revoke a user access from a resource</p>
  /parameters/{parameterId}/list:
    get:
      tags:
        - list
      summary: List available items
      description: >-
        List available items, such as resources. P0 may periodically retrieve
        the list and cache the results for interactive search.
      operationId: list
      parameters:
        - name: parameterId
          in: path
          description: >-
            Parameter ID of the items being listed. The parameter ID is
            configured during setup of the custom resource in P0.
          required: true
          schema:
            type: string
          x-gitbook-description-html: >-
            <p>Parameter ID of the items being listed. The parameter ID is
            configured during setup of the custom resource in P0.</p>
      responses:
        "200":
          $ref: "#/components/responses/ListSuccessResponse"
        "201":
          $ref: "#/components/responses/ListSuccessResponse"
        "202":
          $ref: "#/components/responses/ListSuccessResponse"
        default:
          $ref: "#/components/responses/ErrorResponse"
      security:
        - bearerAuth: []
      x-gitbook-description-document:
        object: document
        data:
          schemaVersion: 8
        nodes:
          - object: block
            type: paragraph
            isVoid: false
            data: {}
            nodes:
              - object: text
                leaves:
                  - object: leaf
                    text: >-
                      List available items, such as resources. P0 may
                      periodically retrieve the list and cache the results for
                      interactive search.
                    marks: []
      x-gitbook-description-html: >-
        <p>List available items, such as resources. P0 may periodically retrieve
        the list and cache the results for interactive search.</p>
components:
  schemas:
    PermissionRequest:
      required:
        - type
        - principal
        - requestor
        - permission
      type: object
      properties:
        requestId:
          type: string
          example: 00iJ7cFPzE8rXb9bwto8
          description: Random identifier for the request generated by P0
          x-gitbook-description-html: <p>Random identifier for the request generated by P0</p>
        type:
          type: string
          example: internalEnvironmentViewerApp
          description: >-
            The value of this field is always going to be the Integration ID
            value you configured in P0.
          x-gitbook-description-html: >-
            <p>The value of this field is always going to be the Integration ID
            value you configured in P0.</p>
        access:
          type: string
          example: customerEnvironment
          description: >-
            The value of this field is always going to be the Access Type value
            you configured in P0.
          x-gitbook-description-html: >-
            <p>The value of this field is always going to be the Access Type
            value you configured in P0.</p>
        principal:
          type: string
          example: access-receiver@example.com
          description: >-
            E-mail address of the principal. Access should be provisioned to the
            user identified by this email.
          x-gitbook-description-html: >-
            <p>E-mail address of the principal. Access should be provisioned to
            the user identified by this email.</p>
        requestor:
          type: string
          example: access-initiator@example.com
          description: >-
            E-mail address of the requestor. Different from the principal only
            if the requestor initiated the access request on behalf of someone
            else.
          x-gitbook-description-html: >-
            <p>E-mail address of the requestor. Different from the principal
            only if the requestor initiated the access request on behalf of
            someone else.</p>
        permission:
          $ref: "#/components/schemas/Access"
        reason:
          type: string
          description: The reason provided by the requestor
          example: I need access to troubleshoot an issue
          x-gitbook-description-html: <p>The reason provided by the requestor</p>
    Access:
      required:
        - type
      properties:
        "{parameterId}":
          type: string
          example: my-customer-inc
          description: >-
            The field name is customized to the parameter ID you configured in
            P0. This parameter ID is also used in the path of your list
            endpoint. The field value (e.g. my-customer-inc) is a unique key
            that identifies an item in your system.
          x-gitbook-description-html: >-
            <p>The field name is customized to the parameter ID you configured
            in P0. This parameter ID is also used in the path of your list
            endpoint. The field value (e.g. my-customer-inc) is a unique key
            that identifies an item in your system.</p>
    ListItem:
      required:
        - label
        - identifier
      properties:
        label:
          type: string
          example: My Customer, Inc.
          description: The display label shown to users when they list resources.
          x-gitbook-description-html: <p>The display label shown to users when they list resources.</p>
        category:
          type: string
          example: Enterprise customers
          description: >-
            Optional. The category of this item. Results are grouped by the
            category in listers.
          x-gitbook-description-html: >-
            <p>Optional. The category of this item. Results are grouped by the
            category in listers.</p>
        identifier:
          type: string
          example: my-customer-inc
          description: >-
            The unique key that identifies the item in your system. Hidden from
            the user, except in the P0 CLI.
          x-gitbook-description-html: >-
            <p>The unique key that identifies the item in your system. Hidden
            from the user, except in the P0 CLI.</p>
      description: >-
        An item that can be picked by the user to populate the requested access
        fields. Filtering the items based on user search term is handled by P0.
      x-gitbook-description-html: >-
        <p>An item that can be picked by the user to populate the requested
        access fields. Filtering the items based on user search term is handled
        by P0.</p>
    ListItems:
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/ListItem"
    Error:
      type: object
      properties:
        type:
          type: string
          enum:
            - public
            - internal
        message:
          type: string
        errorId:
          type: string
        publicMessage:
          type: string
          description: >-
            The message is shown verbatim to the user in the channel they used
            to create the request  (P0 CLI, Slack, MS Teams, etc.).
          x-gitbook-description-html: >-
            <p>The message is shown verbatim to the user in the channel they
            used to create the request  (P0 CLI, Slack, MS Teams, etc.).</p>
      required:
        - type
        - message
      description: >-
        If `type` is "internal", the `errorId` field must be present. P0 will
        display a generic message to the user: "Error in service Internal
        Customer Admin App: P0 encountered an unknown error. Please contact
        p0sec-support@example.com for assistance. (Error ID {errorId}).". If
        `type` is `public`, the `publicMessage` field must be present. P0 will
        display its content verbatim to the user. The regular `message` field
        will be logged in P0 but not displayed to the user. Note: P0 will retry
        all requests that return an error a few times.
      x-gitbook-description-html: >-
        <p>If <code>type</code> is "internal", the <code>errorId</code> field
        must be present. P0 will display a generic message to the user: "Error
        in service Internal Customer Admin App: P0 encountered an unknown error.
        Please contact <a
        href="mailto:p0sec-support@example.com">p0sec-support@example.com</a>
        for assistance. (Error ID {errorId}).". If <code>type</code> is
        <code>public</code>, the <code>publicMessage</code> field must be
        present. P0 will display its content verbatim to the user. The regular
        <code>message</code> field will be logged in P0 but not displayed to the
        user. Note: P0 will retry all requests that return an error a few
        times.</p>
  requestBodies:
    PermissionRequest:
      description: A permission request that needs to be granted or revoked
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PermissionRequest"
      x-gitbook-description-html: <p>A permission request that needs to be granted or revoked</p>
  responses:
    EmptySuccessResponse:
      description: Success
      x-gitbook-description-html: <p>Success</p>
    ListSuccessResponse:
      description: Success
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ListItems"
      x-gitbook-description-html: <p>Success</p>
    ErrorResponse:
      description: Error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
      x-gitbook-description-html: <p>Error</p>
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        P0 generates a keypair during integration setup. Each http request sent
        by P0 to your endpoints contains a JWT signed with the private key in
        the Authorization header. Your endpoints must use the public key
        retrieved during integration setup, to decode the JWT   and verify its
        claims. The claims are: sub (Subject) iss (Issuer), aud (Audience), iat
        (Issued At), exp (Expiry)
      x-gitbook-description-html: >-
        <p>P0 generates a keypair during integration setup. Each http request
        sent by P0 to your endpoints contains a JWT signed with the private key
        in the Authorization header. Your endpoints must use the public key
        retrieved during integration setup, to decode the JWT   and verify its
        claims. The claims are: sub (Subject) iss (Issuer), aud (Audience), iat
        (Issued At), exp (Expiry)</p>
