Skip to content
deploybase

Create a team

POST
/api/v1/me/teams
 
curl --request POST \
  --url https://api.deploybase.eu/api/v1/api/v1/me/teams \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "dpa_version": "example", "entity_name": "Acme B.V.", "interval": "monthly", "name": "Acme web", "plan": "pro", "role": "own", "slug": "acme-web", "terms_version": "example" }'

Creates a new team owned by the signed-in person, with its own identity organization, its own billing and its own data processing agreement. Requires a signed-in user with a confirmed email address: API keys and agent tokens are refused. On a paid plan the team is created awaiting payment (awaiting_payment_until, 48 hours): until its first checkout completes it cannot create projects, deploy or invite, and it is removed if still unpaid at that time. The Free plan is refused while the person owns a Free team or created one in the last 30 days. At most 5 teams per person per 24 hours, deleted ones included. Creating a team does not switch to it. Send an Idempotency-Key header to retry safely: a repeat returns the original team with 200.

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “ Header Parameters ”
Idempotency-Key
string

Up to 255 characters; a repeat returns the first result

Request Body

Section titled “ Request Body ”

The team to create

Media type application/json
object
dpa_version
string
entity_name

EntityName is the organisation named on the team’s data processing agreement, 2 to 200 characters.

string

Example 

Acme B.V.
interval

Interval is monthly or annual; required for a paid plan.

string

Example 

monthly
name

Name is the team’s display name, 1 to 100 characters.

string

Example 

Acme web
plan

Plan is free, starter, pro or scale.

string

Example 

pro
role

Role is own (your organisation) or client (a client who needs their own team).

string

Example 

own
slug

Slug is the team URL, validated like a rename (PATCH /team/profile).

string

Example 

acme-web
terms_version

TermsVersion and DPAVersion echo the versions the page showed (GET /me/team-creation).

string

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

Idempotent replay

Media type application/json
object
data
meta
object
request_id
string
timestamp
string
trace_id
string
data
object
awaiting_payment_until
string
display_label

DisplayLabel is what to show a human. Never empty, even for teams whose name is still a raw Zitadel org UUID — models.Team.DisplayLabel owns that fallback.

string
id
string
interval
string
is_active

IsActive marks the team the current request is acting on.

boolean
is_home

IsHome marks the team the caller’s own Zitadel org maps to. Exactly one entry has it.

boolean
lapse_removal_at
string
lapsed_at

LapsedAt is set while this extra team is blocked as a second Free team of one of its owners (DEP-889): its sites keep serving, but nobody can deploy or create projects until it is paid for again. LapseRemovalAt is when it is deleted if that does not happen. Shown to every member, not just owners: a member who cannot deploy needs to know why.

string
last_active_at
string
name
string
pending_interval
string
pending_plan

PendingPlan and PendingInterval are the paid plan chosen when the team was created, so the waiting-for-payment page can restart the same checkout. Set only alongside AwaitingPaymentUntil, and only for owners.

string
plan

Plan, Interval and AwaitingPaymentUntil are filled only on teams the caller OWNS (DEP-766): what a team pays is the owner’s business, not a member’s. Plan is free, starter, pro or scale; Interval (monthly or annual) is absent on Free. AwaitingPaymentUntil is set while a team created on a paid plan waits for its first payment: the team is removed at that time if it is still unpaid. Such a team reads as Free until the payment lands.

string
role
string
slug
string
status

Status is the team’s lifecycle state, with “suspended” taking precedence over the deletion state machine: a suspended team is usually active, and “active” is exactly the wrong thing to tell someone whose team is closed.

string

Example 

{
  "data": {
    "interval": "monthly",
    "pending_interval": "monthly",
    "pending_plan": "pro",
    "plan": "pro"
  }
}

201

Section titled “ 201 ”

Created

Media type application/json
object
data
meta
object
request_id
string
timestamp
string
trace_id
string
data
object
awaiting_payment_until
string
display_label

DisplayLabel is what to show a human. Never empty, even for teams whose name is still a raw Zitadel org UUID — models.Team.DisplayLabel owns that fallback.

string
id
string
interval
string
is_active

IsActive marks the team the current request is acting on.

boolean
is_home

IsHome marks the team the caller’s own Zitadel org maps to. Exactly one entry has it.

boolean
lapse_removal_at
string
lapsed_at

LapsedAt is set while this extra team is blocked as a second Free team of one of its owners (DEP-889): its sites keep serving, but nobody can deploy or create projects until it is paid for again. LapseRemovalAt is when it is deleted if that does not happen. Shown to every member, not just owners: a member who cannot deploy needs to know why.

string
last_active_at
string
name
string
pending_interval
string
pending_plan

PendingPlan and PendingInterval are the paid plan chosen when the team was created, so the waiting-for-payment page can restart the same checkout. Set only alongside AwaitingPaymentUntil, and only for owners.

string
plan

Plan, Interval and AwaitingPaymentUntil are filled only on teams the caller OWNS (DEP-766): what a team pays is the owner’s business, not a member’s. Plan is free, starter, pro or scale; Interval (monthly or annual) is absent on Free. AwaitingPaymentUntil is set while a team created on a paid plan waits for its first payment: the team is removed at that time if it is still unpaid. Such a team reads as Free until the payment lands.

string
role
string
slug
string
status

Status is the team’s lifecycle state, with “suspended” taking precedence over the deletion state machine: a suspended team is usually active, and “active” is exactly the wrong thing to tell someone whose team is closed.

string

Example 

{
  "data": {
    "interval": "monthly",
    "pending_interval": "monthly",
    "pending_plan": "pro",
    "plan": "pro"
  }
}

400

Section titled “ 400 ”

Bad Request

Media type application/json
object
code
string
details
error
string
meta
object
request_id
string
timestamp
string
trace_id
string

Example generated

{
  "code": "example",
  "details": "example",
  "error": "example",
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}

401

Section titled “ 401 ”

Unauthorized

Media type application/json
object
code
string
details
error
string
meta
object
request_id
string
timestamp
string
trace_id
string

Example generated

{
  "code": "example",
  "details": "example",
  "error": "example",
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}

403

Section titled “ 403 ”

FORBIDDEN (API key or agent token), EMAIL_NOT_CONFIRMED or TEAM_CREATION_UNAVAILABLE

Media type application/json
object
code
string
details
error
string
meta
object
request_id
string
timestamp
string
trace_id
string

Example generated

{
  "code": "example",
  "details": "example",
  "error": "example",
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}

409

Section titled “ 409 ”

SLUG_TAKEN with details.suggestions, FREE_TEAM_LIMIT with details.reason, LEGAL_VERSION_STALE with the current versions, IDEMPOTENCY_KEY_REUSED

Media type application/json
object
code
string
details
error
string
meta
object
request_id
string
timestamp
string
trace_id
string

Example generated

{
  "code": "example",
  "details": "example",
  "error": "example",
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}

422

Section titled “ 422 ”

INVALID_INPUT or SLUG_RESERVED, with details.field

Media type application/json
object
code
string
details
error
string
meta
object
request_id
string
timestamp
string
trace_id
string

Example generated

{
  "code": "example",
  "details": "example",
  "error": "example",
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}

429

Section titled “ 429 ”

TEAM_CREATE_RATE_LIMITED, with Retry-After and details.retry_after

Media type application/json
object
code
string
details
error
string
meta
object
request_id
string
timestamp
string
trace_id
string

Example generated

{
  "code": "example",
  "details": "example",
  "error": "example",
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}

500

Section titled “ 500 ”

Internal Server Error

Media type application/json
object
code
string
details
error
string
meta
object
request_id
string
timestamp
string
trace_id
string

Example generated

{
  "code": "example",
  "details": "example",
  "error": "example",
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}

502

Section titled “ 502 ”

PROVISIONING_FAILED

Media type application/json
object
code
string
details
error
string
meta
object
request_id
string
timestamp
string
trace_id
string

Example generated

{
  "code": "example",
  "details": "example",
  "error": "example",
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}

Live f79d25b6 built