Skip to content
Getting started

Teams

What is a Team?

A team is a collaborative unit where multiple users share API Keys and a wallet. You can create a team to collaborate with others, and API charges incurred from the team's Keys (team Keys or member Keys) are all deducted from the shared team wallet.

Use Cases

  • Multiple developers working on the same project sharing API quota and costs
  • Providing individual API Keys to sales or partners while sharing the company's team wallet
  • Agencies or studios managing API usage for multiple clients

Creating and Joining a Team

Creating a Team

  1. Log in to the console and navigate to the "Teams" page
  2. Click "Create Team" and enter a team name
  3. Upon completion, you become the team's Owner

Creation Limit: Each account can create a maximum of 3 teams.

Inviting Members

  1. In the team details page, click "Invite Member"
  2. Enter the invitee's email and role (Admin or Member)
  3. The invitation is valid for 7 days

Invitees must:

  • Register with the platform using that email address
  • Log in and accept the invitation

Important: Only users logged in with the invited email can accept the invitation. Invitations cannot replace registration; invitees must register an account themselves.

Joining a Team

When you receive an invitation:

  1. Log in to the console and go to "Pending Invitations"
  2. Review the team, inviter, and role information (the inviter's email is partly hidden, e.g. ow***@example.com)
  3. Click "Accept" or "Decline"

Join Limit: Each account can join a maximum of 10 teams (including teams you create); each account can own a maximum of 3 teams.

Roles and Permissions

Teams have three roles with the following permissions:

FeatureOwnerAdminMember
View Member List✓✓✓
Invite Members✓✓—
Remove Member✓✓—
Remove Admin✓——
Change Member Role✓——
Transfer Owner✓——
Dissolve Team✓——
View Team Balance✓✓✓
Top Up Team Wallet✓——
View Recharge History✓✓—
View All Members' Usage✓✓—
View Personal Usage✓✓✓(own only)
Create Team Key✓✓—
Create Member Key✓✓✓(own only)
Manage Keys✓✓✓(own only)

Notes:

  • Balance is visible to all roles (Members can see the team balance figure)
  • Top-ups, transaction history, and all-member usage are only visible to Owner/Admin
  • Members can only view their own Keys and usage
  • Admin can only remove Members; only Owner can remove Admins; Owner cannot be removed and must transfer first
  • Other people's e-mails (members, invitations, key holders, usage rows, the payer of an order) are masked by the server, e.g. wi***@gmail.com; you see your own in full

Member Keys vs. Team Keys

Member Key

  • Holder: The member who created it
  • Cost Source: Team wallet (never the personal balance)
  • Access: Personal use only
  • Leaving or removed: When the member leaves or is removed from the team, the membership is deleted and the member's member Keys are revoked in the same transaction; subsequent API calls return 401

Team Key

  • Holder: Held in the Owner's name (only Owner/Admin can create one)
  • Cost Source: Team wallet
  • Access: Shared by all team members
  • Leaving or transfer: A member leaving or being removed does not affect team Keys; on an ownership transfer the team Keys move to the new Owner

Team Wallet and Top-Ups

Top-Up Methods

Only the Owner can top up the team wallet. Supported payment methods:

  • Stripe: Credit/debit cards
  • OxaPay: Multiple payment options

Top-Up Process

  1. In the team details page, click "Top Up"
  2. Select payment method and amount
  3. After payment, the amount automatically enters the team wallet
  4. The page will return to the team page showing "Top-up successful" or "Cancelled" notification

Important:

  • When the page returns, the system refetches the backend balance; top-up is confirmed only after payment callback
  • If processing is slow, the page will show "Processing"

QR Code and Status Fields in Top-Up Orders

QR Code (qrCode)

The qrCode field of a top-up order is provided by the payment provider to display the payment QR code. Please note:

  • The format is not standardized by this platform and may be a URL, base64-encoded string, or other format
  • Do not make assumptions about the format; refer to the payment provider's documentation
  • OxaPay returns null when no QR code is available; Stripe orders do not have a qrCode field

Status Fields: status vs. publicStatus

Top-up orders have two status fields for different purposes:

FieldDefinitionExample ValuesUse Case
statusRaw status string (payment provider status and local processing status)OxaPay: new, paid, expired etc.; Local: creating, creation_failed etc.Internal logging, debugging
publicStatusPlatform-normalized status (defined)pending, partial, paid, refunded, failed, expiredExternal API, user interface display

OxaPay-supported status values (for reference; follow PROVIDER_STATUSES in src/lib/payments/oxapay/store.ts and keep this list in sync):

  • Official lowercase values: new, waiting, paying, paid, underpaid, refunding, refunded, expired
  • manual_accept: merchant manually accepts an invoice in OxaPay dashboard; validation and idempotency match paid, and the local order amount is credited. Sandbox orders and orders for disbanded teams are not credited. Until credited, publicStatus remains pending.
  • Local values: creating, creation_failed, creation_unknown, creation_void

Usage Recommendations:

  • When displaying payment progress to users, use publicStatus (standardized, stable)
  • When polling GET /api/me/topup/{stripe|oxapay}/:id, focus on publicStatus; you do not need to parse status. The response's stale is false when the poll refreshed the order successfully and true when it could not (for example, no provider reference, a mismatch, or a lookup error); it is not an order-age indicator.
  • status is retained as raw provider information for technical support and debugging

Team Consumption

  • API requests using team Keys or member Keys are charged only to the team wallet
  • Team consumption does not affect personal balance, personal usage, or personal accounting
  • Team consumption is excluded from referral bonus calculations
  • When team wallet balance is insufficient (≤ 0), using a team Key or member Key returns HTTP 402

Removing Members and Dissolving a Team

Removing a Member

  • Owner can remove Admins and Members
  • Admin can only remove Members
  • The Owner cannot be removed
  • The membership is removed and the member's member Keys are revoked in the same transaction (subsequent API calls return 401); their personal Keys are not affected

Leaving a Team

  • Admins and Members can voluntarily leave a team
  • The Owner must first transfer ownership to another member, otherwise the request returns owner_must_transfer
  • On leaving, your member Keys are revoked in the same transaction (they return 401 afterwards); personal Keys are retained

Transferring Ownership

  • Only the Owner can transfer ownership to another member of the team
  • After the transfer the former Owner becomes an Admin, and the team Keys move to the new Owner

Dissolving a Team

Only Owner can dissolve a team with conditions:

  • Team balance is ≤ 0 (no remaining balance)
  • No unsettled recharges

Upon dissolution (one transaction):

  • Every Key of the team (team Keys and member Keys) is revoked
  • Open invitations are revoked and every membership is removed
  • The team's status becomes disbanded; the team itself, its wallet ledger and its call records (traces) are kept, nothing is deleted

Limits and Constraints

Member Limit

  • Each team can have a maximum of 10 members (including pending invitations)

Key Limit

  • Each team can have a maximum of 50 Keys (team Keys and member Keys combined; revoked Keys do not count)

Creation and Join Limits

  • Each user can own a maximum of 3 teams
  • Each user can join a maximum of 10 teams (including teams you create)

Referrals and Reward Codes

  • Team top-ups and consumption are excluded from referral bonus base
  • Claiming an invite code needs no top-up (since 2026-11-09), so teams play no part in it

Features Not Yet Supported

The following features will be supported in future releases and are currently unavailable:

  • Member Monthly Usage Limit: Not available
  • Team Rental: Team Keys cannot be used as rental Keys
  • Balance Withdrawal: Team wallet balances cannot be transferred back to personal accounts

FAQ

Q: How do I change a member's role?

A: Go to team details → member list → click the member → select new role. Only Owner has this permission.

Q: Can a Member create Keys?

A: Members can only create "member Keys" (charged to the team wallet). Creating "team Keys" requires Owner/Admin permission.

Q: What happens if the Owner is banned?

A: While the Owner is banned, every Key of the team (team Keys and member Keys) gets 403 on API calls, and members cannot use them.

Q: What if an invitation expires?

A: Invitations are valid for 7 days. After expiration, Owner/Admin must send a new invitation.

Q: How are charges settled after a member leaves?

A: Team charges are deducted in real-time upon request. Leaving the team does not affect previously incurred charges.