Role-Based Access Control
API Hub for Contract Testing uses a flexible team-based Role-Based Access Control (RBAC) model to manage access to contracts, applications, and features. This ensures users can only interact with resources in ways allowed by their assigned roles and team membership.
This model supports simple team structures and scales to complex organizations.
Core concepts
Users: Individuals who interact with API Hub for Contract Testing using the UI, API, or CLI.
Roles: Defined global collections of permissions assigned to users.
Permissions: Actions a user can perform. Some permissions are limited to specific teams or resources.
Teams: Logical groups of users that own applications and resources.
Applications: Team-owned services that participate in contract testing.
Contracts: The data generated from interactions between applications.
Resources: Include secrets, webhooks, test results, and other team-scoped assets.
How it works
API Hub for Contract Testing uses a flexible RBAC model, where:
Users are assigned one or more global roles
Roles grant a set of permissions
Some permissions are scoped to specific teams or resources
Note
While roles are assigned globally to a user, many permissions are evaluated in context, particularly when scoped to a team.
Example
A user with the
contract_data:manage:team
permission can modify contract data only for applications owned by teams they belong to.A user with
user:invite
(no scope) can invite users across the entire organization.
The following are the effective permissions:
Their globally assigned roles.
The permissions granted by roles.
The team or resource scope (if applicable) of permissions.
The team to which the member is aassigned, when the permission is scoped to a team.
Special case: Team Administrator
The Team Administrator is a special permission-based role assigned to a user for a specific team. It is implemented using a scoped permission like:
team:manage:{team_uuid}
This allows for delegated administration of a team without giving the user global administrative rights.
Note
Roles are additive. There are no negated permissions in API Hub for Contract Testing.
Conceptual model

Example: Team-based access
This guide walks you through an example with two teams, three applications, and three users, one of whom is a platform administrator.
Team structure
Team | Applications | Users |
---|---|---|
A | ProductService, OrderService | User 1 |
B | OrderService, AuthService | User 2 |
User access and roles
User | Team | Role | Access Rights |
---|---|---|---|
User 1 | A | Test Maintainer | ProductService, OrderService |
User 2 | B | Test Maintainer | OrderService, AuthService |
User 3 | - | Administrator | all |
User 1 and User 2 can only act on applications owned by their assigned teams.
User 3, as an Administrator, can access and manage any application or contract in the system.
If User 1 attempts to publish a contract for an application not owned by their team (for example, AuthService), they receive a permissions error.
Example error
Failed to tag versions due to error: PactBroker::Client::Error – Authorization failed (403) One or more pacts failed to be published
This demonstrates how access is enforced based on both ownership and RBAC permissions.
Note
See Predefined roles for more details on role capabilities.
See also
Visit Predefined roles for a list of the default roles.
Visit Permissions Overview for a list of supported permissions.