Skip to content
Spacefast Docs
Esc
↑↓navigate↵open⌘Jpreview

Create a team

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.

POST/v1/teams
Authorization
AuthorizationBearer token · headerrequired

Better Auth session, OAuth access token, OAuth client-credentials token, or sfm_ Space machine credential.

or
AuthorizationOAuth2 access token · headerrequired

OAuth 2.0 with explicit Spacefast capability scopes. Use the authorization-code flow for people and client credentials for machines.

Scopes:teams:create
Request body
requiredapplication/json
namestringrequired

Display name for the new team.

min length 1 · max length 255
slugstring

Optional URL slug. If omitted, the server generates the lowest available slug.

min length 1 · max length 255 · matches ^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$
Responses
201

Response for status 201

$schemastring<uri>

Canonical JSON Schema URL for this response body. The server also sends it in the Link: rel="describedby" response header.

dataobjectrequired
Show properties
idstringrequired

The team id (the Better Auth team id in the main tenant).

namestringrequired

The team display name.

slugstringrequired

URL-safe team slug, unique per tenant.

rolestringrequired

Requesting member's role; member for non-session credentials.

Allowed:owneradminmember
planstringrequired

Resolved plan code from the active subscription.

Allowed:freegoplusgoldenterpriseinternal
partnerobject | nullrequired

Partner access for this team, or null when the team is not a partner.

Show properties
Any of:
object
enabledAtstring<date-time>required

The instant this team became a partner.

matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
null
null
defaultDataLocationstringrequired

Default placement region for new spaces; "auto" lets placement decide.

createdAtstring<date-time>required
matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
updatedAtstring<date-time>required
matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
logostring | nullrequired

Optional team logo URL.

metadatastring | nullrequired

Opaque team metadata stored by the client.

stripeCustomerIdstring | nullrequired

Stripe customer id linked to this team; null until billing is initialized.

systemSpaceIdstring | nullrequired

The space that supplies this team's page, theme, and presentation defaults.

manifestStatusobjectrequired

The status of the restricted manifest from the team's system space.

Show properties
itemsobject[]required

Per-key materialization status.

Show properties
Array of object
keystringrequired

The manifest key this item materializes.

statestringrequired

Where the last reconcile landed this key.

Allowed:pendingactivefailed
detailstring

Human-readable reason, present when the state warrants one (typically failed).

sincestring<date-time>required

When this key last CHANGED state — stable across no-op re-runs, so it reads as <state> since ….

matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
challengestring

Sign this challenge with every new issuer key, using the supplied audience, then republish proofs. Existing active keys remain usable while rotation is pending.

audiencestring

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.

sourceVersionIdstring | nullrequired

The system space's live version every item was converged from, or null when nothing is materialized.

presentationobject | nullrequired

The presentation from the team's system space, or null when no value is active.

Show properties
Any of:
object
namestring
min length 1 · max length 255
logostring
min length 1 · max length 2048 · matches ^https:\/\/[^\s"'<>\\*]+$
supportUrlstring
min length 1 · max length 2048 · matches ^https:\/\/[^\s"'<>\\*]+$
claimOriginstring
min length 1 · max length 2048 · matches ^https:\/\/[^\s"'<>\\*]+$
accessHandoffOriginstring
min length 1 · max length 2048 · matches ^https:\/\/[^\s"'<>\\*]+$
problemDocsBaseUrlstring
min length 1 · max length 2048 · matches ^https:\/\/[^\s"'<>\\*]+$
contactsobject

Named contact URLs or addresses shown to claimants and partners.

null
null
default

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

$schemastring<uri>

Canonical JSON Schema URL for this response body. The server also sends it in the Link: rel="describedby" response header.

typestringrequired

Problem type URI resolving to the error docs page. The server derives it mechanically from code against the docs origin.

titlestringrequired

Short human-readable summary of the problem type. The server derives it mechanically from code.

statusintegerrequired

HTTP status code of this response, repeated in the body.

min -9007199254740991 · max 9007199254740991
detailstringrequired

Human-readable failure explanation for this occurrence.

codestringrequired

Stable snake_case error code naming the failed public contract.

pointerstring

RFC 6901 JSON Pointer into the failing request field, for example "/files/37/path", on validation failures.

detailsobject

Machine-readable context for the error code.

suggestionsstring[]

Actionable recovery steps safe to show in dashboards, SDKs, and CLI output.

nextstring[]

Copy-pasteable commands or API requests an agent can run next.

requestIdstringrequired

The request id to quote when contacting support.

Try it
Server
Authorization
Bodyapplication/json
Request
curl -X POST 'https://api.spacefast.com/v1/teams' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "slug": "string"
}'
Response
{
  "$schema": "http://example.com",
  "data": {
    "id": "string",
    "name": "string",
    "slug": "string",
    "role": "owner",
    "plan": "free",
    "partner": {
      "enabledAt": "2019-08-24T14:15:22Z"
    },
    "defaultDataLocation": "string",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z",
    "logo": "string",
    "metadata": "string",
    "stripeCustomerId": "string",
    "systemSpaceId": "string",
    "manifestStatus": {
      "items": [
        {
          "key": "string",
          "state": "pending",
          "detail": "string",
          "since": "2019-08-24T14:15:22Z",
          "challenge": "string",
          "audience": "string"
        }
      ],
      "sourceVersionId": "string"
    },
    "presentation": {
      "name": "string",
      "logo": "string",
      "supportUrl": "string",
      "claimOrigin": "string",
      "accessHandoffOrigin": "string",
      "problemDocsBaseUrl": "string",
      "contacts": {
        "property1": "string",
        "property2": "string"
      }
    }
  }
}