A team is the WorkOS account that owns a user’s environments and billing. A platform creates one team per user, and the user named as admin receives an email invitation to it.
Example Team
cURL
team
Creates a team along with its default project, a staging environment, and a production environment. An admin invitation is sent to admin_email, onboarding is marked complete with AuthKit enabled, and the calling platform is authorized to act inside the team.
cURL
| curl --request POST \ | |
| --url "https://api.workos.com/platform/teams" \ | |
| --header "Authorization: Bearer $PLATFORM_ACCESS_TOKEN" \ | |
| --header "Content-Type: application/json" \ | |
| -d @- <<'BODY' | |
| { | |
| "admin_email": "alice@example.com", | |
| "name": "Alice's Team" | |
| } | |
| BODY |
| { | |
| "object": "team", | |
| "id": "team_01K4BN3VKH8AFZC5J334QZY3PM", | |
| "name": "Alice's Team", | |
| "production_state": "Inactive", | |
| "production_enabled_at": null, | |
| "created_at": "2026-01-15T07:41:09.394Z", | |
| "updated_at": "2026-01-15T07:41:09.394Z" | |
| } |
POST/platform
Parameters
Returns
- 409 (
user_already_exists): a WorkOS user already exists with that email address. Ask for a different address, or move the user through a flow that connects their existing team.
Returns a team, and doubles as a health check on the platform’s access to it. Read production_state before attempting to create a production environment.
cURL
| curl --request GET \ | |
| --url "https://api.workos.com/platform/teams/team_01K4BN3VKH8AFZC5J334QZY3PM" \ | |
| --header "Authorization: Bearer $PLATFORM_ACCESS_TOKEN" |
| { | |
| "object": "team", | |
| "id": "team_01K4BN3VKH8AFZC5J334QZY3PM", | |
| "name": "Alice's Team", | |
| "production_state": "Inactive", | |
| "production_enabled_at": null, | |
| "created_at": "2026-01-15T07:41:09.394Z", | |
| "updated_at": "2026-01-15T07:41:09.394Z" | |
| } |
GET/platform
Parameters
Returns
- 404 (
team_not_found): the team doesn’t exist, or the platform’s access to it has been revoked. Both are terminal.
Environment Continue to the next section
Up next