---
title: "Create a team"
method: POST
path: "/v1/teams"
tags: ["Teams"]
---

# Create a team

`POST /v1/teams`

## Request

- Base URL: `https://api.spacefast.com`
- URL: `https://api.spacefast.com/v1/teams`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.spacefast.com/v1/auth/oauth2/authorize`, token URL `https://api.spacefast.com/v1/auth/oauth2/token`; client credentials, token URL `https://api.spacefast.com/v1/auth/oauth2/token`, scopes: `teams:create`)

Creates a new team owned by your credential's user. Self-serve teams are created in the main tenant and the caller becomes the team owner.

## Request body

- object
  - `name` string, required: Display name for the new team.
  - `slug` string: Optional URL slug. If omitted, the server generates the lowest available slug.

## Response `201`

Response for status 201

- object
  - `$schema` string, uri: Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header.
  - `data` object, required
    - `id` string, required: The team id (the Better Auth team id in the main tenant).
    - `tenantId` string, required: The owning tenant id; `ten_main` for self-serve teams.
    - `name` string, required: The team display name.
    - `slug` string, required: URL-safe team slug, unique per tenant.
    - `role` 'owner' | 'admin' | 'member', required: Requesting member's role; member for non-session credentials.
    - `plan` 'free' | 'go' | 'plus' | 'gold' | 'enterprise' | 'internal', required: Resolved plan code from the active subscription.
    - `partner` object, nullable, required: Partner access for this team, or null when the team is not a partner.
      - `enabledAt` string, date-time, required: The instant this team became a partner.
    - `defaultDataLocation` string, required: Default placement region for new spaces; "auto" lets placement decide.
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
    - `logo` string, nullable, required: Optional team logo URL.
    - `metadata` string, nullable, required: Opaque team metadata stored by the client.
    - `stripeCustomerId` string, nullable, required: Stripe customer id linked to this team; null until billing is initialized.
    - `systemSpaceId` string, nullable, required: The space that supplies this team's page, theme, and presentation defaults.
    - `manifestStatus` object, required: The status of the restricted manifest from the team's system space.
      - `items` object[], required: Per-key materialization status.
        - `key` string, required: The manifest key this item materializes.
        - `state` 'pending' | 'active' | 'failed', required: Where the last reconcile landed this key.
        - `detail` string: Human-readable reason, present when the state warrants one (typically `failed`).
        - `since` string, date-time, required: When this key last CHANGED state — stable across no-op re-runs, so it reads as `<state> since …`.
        - `challenge` string: Sign this challenge with every new issuer key, using the supplied audience, then republish proofs. Existing active keys remain usable while rotation is pending.
        - `audience` string: `tokenIssuers` only: the server-minted opaque audience for the issuer this key materialized. Not a secret — it rides in every partner token's `aud` claim and is verified server-side — and the partner needs it to sign the activation proof and to mint tokens, so it is served here rather than handed over out of band.
      - `sourceVersionId` string, nullable, required: The system space's live version every item was converged from, or null when nothing is materialized.
    - `presentation` object, nullable, required: Partner-facing branding and links for the white-label surface.
      - `name` string
      - `logo` string
      - `supportUrl` string
      - `claimOrigin` string
      - `accessHandoffOrigin` string
      - `problemDocsBaseUrl` string
      - `contacts` object: Named contact URLs or addresses shown to claimants and partners.

## Other responses

- `default`: Problem details (RFC 9457). Any 4xx/5xx response is one `application/problem+json` document.

---

[API](https://skmtc.dev/spacefast/apis/spacefast-api.md) · [All operations](https://skmtc.dev/spacefast/apis/spacefast-api/llms.txt) · [OpenAPI document](https://skmtc.dev/spacefast/apis/spacefast-api/revisions/bd165bc7c983?raw)