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 sk_example_123456789" \ | |
| --header "Content-Type: application/json" \ | |
| -d @- <<'BODY' | |
| { | |
| "admin_email": "alice@example.com", | |
| "name": "Example Team" | |
| } | |
| BODY |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.platform_teams.create_team( | |
| admin_email: "alice@example.com", | |
| name: "Example Team" | |
| ) |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.platform_teams.create_team(admin_email="alice@example.com", name="Example Team") |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v10" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.PlatformTeams().CreateTeam(context.Background(), &workos.PlatformTeamsCreateTeamParams{ | |
| AdminEmail: "alice@example.com", | |
| Name: "Example Team", | |
| }) | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos | |
| ->platformTeams() | |
| ->createTeam(adminEmail: "alice@example.com", name: "Example Team"); |
| import com.workos.WorkOS; | |
| import com.workos.platformteams.PlatformTeamsApi.CreateTeamOptions; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| CreateTeamOptions options = CreateTeamOptions.builder() | |
| .adminEmail("alice@example.com") | |
| .name("Example Team") | |
| .build(); | |
| workos.platformTeams.createTeam(options); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.PlatformTeams.CreateTeamAsync(new PlatformTeamsCreateTeamOptions { | |
| AdminEmail = "alice@example.com", | |
| Name = "Example Team", | |
| }); |
| use workos::Client; | |
| use workos::platform_teams::CreateTeamParams; | |
| #[tokio::main] | |
| async fn main() -> Result<(), workos::Error> { | |
| let client = Client::builder() | |
| .api_key("sk_example_123456789") | |
| .client_id("client_123456789") | |
| .build(); | |
| let _result = client | |
| .platform_teams() | |
| .create_team( | |
| CreateTeamParams { | |
| admin_email: "alice@example.com".into(), | |
| name: "Example Team".into(), | |
| ..Default::default() | |
| } | |
| ) | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "object": "team", | |
| "id": "team_01JX9AN6E02HAG2Q2CKGC1XT5W", | |
| "name": "Example Team", | |
| "production_state": "Active", | |
| "production_enabled_at": "2024-01-01T00:00:00.000Z", | |
| "created_at": "2024-01-01T00:00:00.000Z", | |
| "updated_at": "2024-01-01T00:00:00.000Z" | |
| } |
POST/platform
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 "https://api.workos.com/platform/teams/team_01JX9AN6E02HAG2Q2CKGC1XT5W" \ | |
| --header "Authorization: Bearer sk_example_123456789" |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.platform_teams.get_team(team_id: "team_01JX9AN6E02HAG2Q2CKGC1XT5W") |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.platform_teams.get_team(team_id="team_01JX9AN6E02HAG2Q2CKGC1XT5W") |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v10" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.PlatformTeams().GetTeam(context.Background(), "team_01JX9AN6E02HAG2Q2CKGC1XT5W") | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos->platformTeams()->getTeam(teamId: "team_01JX9AN6E02HAG2Q2CKGC1XT5W"); |
| import com.workos.WorkOS; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| workos.platformTeams.getTeam("team_01JX9AN6E02HAG2Q2CKGC1XT5W"); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.PlatformTeams.GetTeamAsync("team_01JX9AN6E02HAG2Q2CKGC1XT5W"); |
| use workos::Client; | |
| #[tokio::main] | |
| async fn main() -> Result<(), workos::Error> { | |
| let client = Client::builder() | |
| .api_key("sk_example_123456789") | |
| .client_id("client_123456789") | |
| .build(); | |
| let _result = client | |
| .platform_teams() | |
| .get_team("team_01JX9AN6E02HAG2Q2CKGC1XT5W") | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "object": "team", | |
| "id": "team_01JX9AN6E02HAG2Q2CKGC1XT5W", | |
| "name": "Example Team", | |
| "production_state": "Active", | |
| "production_enabled_at": "2024-01-01T00:00:00.000Z", | |
| "created_at": "2024-01-01T00:00:00.000Z", | |
| "updated_at": "2024-01-01T00:00:00.000Z" | |
| } |
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.