Authentication and Authorization


All calls to the PactFlow APIs require a Bearer Token, referred to in PactFlow as an API Token.

Include the API Token in the Authorization HTTP header of each request with the value Bearer {API_TOKEN}, replacing {API_TOKEN} with the actual value of your API Token from PactFlow.

See here for information on how to retrieve an API Token from PactFlow.

Authentication Errors

When the API does not receive a valid token, it will return a 401 status code.


Roles and Permissions

PactFlow's Roles and Permissions model protect all API resources. These permissions are expressed in the form resource:action:scope.

Each resource will have the applicable permissions required documented as scopes on the security section for the endpoint.

NOTE: As the scope is dynamic and based on context, we cannot always express the exact permission required in a static OpenAPI document. For example, attempting to modify a resource in your team requires the :team suffix, otherwise it requires the :* suffix. Cannot be known in advance, so the scopes should be considered advisory in nature.

For example, given the following endpoint security definition:

        - bearerAuth:
            - 'webhook:manage:team'
            - 'webhook:manage:*'

To call the API, the API Token associated with the User will require one of the relevant webhook permission scopes (*, team, etc.) on their role. That is, the scopes required are indicative only.

Authorization Errors

When a valid authorization token is provided, but the calling user has incorrect permissions, the API will return a 403 status code.

Read Only and Read-Write API Tokens

The exception to the rules above, is that you must use a read-write API Token when calling any non-GET API resource. Ensure you are using the correct token when you retrieve your API Token.

When executing pact tests during development on local machines, we recommend using read-only tokens to avoid accidentally publishing data from outside of CI. Read-write tokens should typically only be used in CI pipelines, or for administrative purposes (e.g., automated user/team management).