Authentication and Authorization
Authentication
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.
Authorization
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:
/webhooks:
post:
security:
- 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).