<!-- llms.txt: https://workos.com/llms.txt -->

# Team

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.

:::code-group{title="Example Team"}

```json language="curl"
{
  "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"
}
```

:::

## Endpoints

- [Create a team](https://workos.com/docs/reference/platform/team/create)
- [Get a team](https://workos.com/docs/reference/platform/team/get)

## Create a 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.

:::code-group

```bash language="curl" title="Request" tab="1"
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
```

```rb language="ruby" title="Request" tab="1"
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"
)
```

```py language="python" title="Request" tab="1"
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")
```

```go language="go" title="Request" tab="1"
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 language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->platformTeams()
    ->createTeam(adminEmail: "alice@example.com", name: "Example Team");
```

```java language="java" title="Request" tab="1"
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);
```

```cs language="dotnet" title="Request" tab="1"
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",
});
```

```rust language="rust" title="Request" tab="1"
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(())
}
```

```json language="json" title="Response" tab="2"
{
  "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"
}
```

:::

### Error responses

- **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.

## Get a 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.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/platform/teams/team_01JX9AN6E02HAG2Q2CKGC1XT5W" \
  --header "Authorization: Bearer sk_example_123456789"
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.platform_teams.get_team(team_id: "team_01JX9AN6E02HAG2Q2CKGC1XT5W")
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.platform_teams.get_team(team_id="team_01JX9AN6E02HAG2Q2CKGC1XT5W")
```

```go language="go" title="Request" tab="1"
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 language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos->platformTeams()->getTeam(teamId: "team_01JX9AN6E02HAG2Q2CKGC1XT5W");
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.platformTeams.getTeam("team_01JX9AN6E02HAG2Q2CKGC1XT5W");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.PlatformTeams.GetTeamAsync("team_01JX9AN6E02HAG2Q2CKGC1XT5W");
```

```rust language="rust" title="Request" tab="1"
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(())
}
```

```json language="json" title="Response" tab="2"
{
  "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"
}
```

:::

### Error responses

- **404** (`team_not_found`): the team doesn't exist, or the platform's access to it has been revoked. Both are terminal.

### team

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | "team" | Yes | Distinguishes the team object. |
| `id` | string | Yes | Unique identifier of the team. |
| `name` | string | Yes | The name of the team. |
| `production_state` | "Active" \| "Inactive" \| "Suspended" \| "Deleting" | Yes | Whether the team can host production environments. `Active` means billing is set up. `Inactive` means a team admin must add a payment method in the WorkOS Dashboard. `Suspended` and `Deleting` mean the team can't be provisioned into. |
| `production_enabled_at` | string | No | The timestamp when production was enabled for the team, or `null` if it never has been. |
| `created_at` | string | Yes | The timestamp when the team was created. |
| `updated_at` | string | Yes | The timestamp when the team was last updated. |

### POST /platform/teams

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `admin_email` | string | Yes | The email address of the person who will administer the team. An invitation is sent to this address. |
| `name` | string | Yes | The name of the team. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `team` | object | Distinguishes the team object. |

### GET /platform/teams/{team_id}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `team_id` | string | Yes | The ID of the team. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `team` | object | Distinguishes the team object. |