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
- Log in to the console and navigate to the "Teams" page
- Click "Create Team" and enter a team name
- Upon completion, you become the team's Owner
Creation Limit: Each account can create a maximum of 3 teams.
Inviting Members
- In the team details page, click "Invite Member"
- Enter the invitee's email and role (Admin or Member)
- 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:
- Log in to the console and go to "Pending Invitations"
- Review the team, inviter, and role information (the inviter's email is partly hidden, e.g.
ow***@example.com) - 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:
| Feature | Owner | Admin | Member |
|---|---|---|---|
| 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
- In the team details page, click "Top Up"
- Select payment method and amount
- After payment, the amount automatically enters the team wallet
- 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
nullwhen no QR code is available; Stripe orders do not have aqrCodefield
Status Fields: status vs. publicStatus
Top-up orders have two status fields for different purposes:
| Field | Definition | Example Values | Use Case |
|---|---|---|---|
status | Raw status string (payment provider status and local processing status) | OxaPay: new, paid, expired etc.; Local: creating, creation_failed etc. | Internal logging, debugging |
publicStatus | Platform-normalized status (defined) | pending, partial, paid, refunded, failed, expired | External 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 matchpaid, and the local order amount is credited. Sandbox orders and orders for disbanded teams are not credited. Until credited,publicStatusremainspending.- 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 onpublicStatus; you do not need to parsestatus. The response'sstaleisfalsewhen the poll refreshed the order successfully andtruewhen it could not (for example, no provider reference, a mismatch, or a lookup error); it is not an order-age indicator. statusis 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.