Team

How a team owns billing, members, API keys, and the projects that belong to it.

A team owns billing, members, and API keys, and every project belongs to exactly one team. The team's plan supplies the seat, viewer, project, and invitation limits that the projects and billing pages apply.

Team and project

Every project belongs to exactly one team, and the team owns the shared wallet that the project's usage is debited from. The team also owns the member list and the API keys that act on its behalf, so a project's access always resolves through a team membership.

See Projects for a project's lifecycle, access, membership roles, and agent configuration.

Members and roles

A team member holds exactly one of five roles. The role decides what the member may do in the team and whether the membership consumes a paid seat.

RoleWhat it can doSeat
ownerManage the team and billing, assign every role including owner, and demote or remove another owner.Billed
adminManage the team and billing and assign every role except owner.Billed
memberWork in the team's projects, start their own checkout, and issue a personal API key when the policy allows.Billed
billingRead billing data and start their own checkout; cannot administer billing or act for the team.Billed
viewerRead-only access; does not act for the team.Not billed

A team always keeps at least one owner, so the last owner cannot be demoted or removed.

owner and admin are the team's administrators. The billing and viewer roles do not act for the team on its behalf, so no credential or assistant acts for the team through their membership.

Invitations

An email invitation names one account and admits only that account. A link invitation has no email, and every holder may join through it until it expires or is revoked.

An invitation starts as pending and ends as accepted, revoked, or expired. Every invitation expires after seven days. The invited role defaults to member, and the team's plan must allow invitations before an invitation can be created.

A pending email invitation reserves the capacity its role needs while it waits, so that capacity cannot be given to someone else. An invitation for a billed role holds a paid seat; an invitation for the viewer role holds a viewer slot instead. A link invitation reserves no capacity while pending; each join through the link is checked against the team's limits when it happens.

Reading teams through the API

Three routes read a team and its members:

  • GET /v1/teams lists the teams the key can act for.
  • GET /v1/teams/:teamId reads one team.
  • GET /v1/teams/:teamId/members lists the team's members with their roles.

All three require the workspace read capability.

export API_ORIGIN="https://api.openfactor.ai"
export API_KEY="<your API key>"

curl -sS "$API_ORIGIN/v1/teams" \
  -H "Authorization: Bearer $API_KEY" |
  jq '.teams[] | {id, name, status, role: .membership.role}'

curl -sS "$API_ORIGIN/v1/teams/TEAM_ID/members" \
  -H "Authorization: Bearer $API_KEY" |
  jq '.members[] | {email, role}'

The team object reports status as active or archived, and its membership.role is the caller's own role in that team.

Next steps

  • Projects - a project's lifecycle, access, membership roles, and agent configuration
  • Seats - how the seat quantity affects the recurring price and included balance
  • Plan limits - the seat, viewer, project, and invitation limits a plan supplies
  • API overview - authentication, capabilities, action grants, and endpoint families