Skip to main content

invite Workspace Owner

POST /api/auth/workspace-invitations

Canonical origin only. POST requires an exact Origin header and application/json. Browser sessions use an HttpOnly, Secure, SameSite=Strict cookie. Setup sessions cannot access tenant APIs. Tenant provisioning and global audit require a platform operator; member administration requires a tenant administrator. SSO is deferred. Workspace-owner invitations are operator-only except preview and accept, which require the single-use email token in the JSON body. Creating an invitation uses a client-generated UUID id for idempotency. Repeating the same ID and details returns its saved state without sending another email. Resending invalidates the previous token. Acceptance reserves the chosen workspace details, initializes the tenant idempotently, consumes the invitation, and issues only a restricted MFA-setup session. Tokens expire after 24 hours. Accepted accounts must complete MFA before tenant access. Never place tokens in query strings.

Authentication​

The following OpenAPI alternatives describe accepted authentication. Browser mutations also require the canonical Origin header.

[
  {
    "browserSession": []
  }
]

Parameters​

[]

Request body​

{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "name": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "email",
          "name"
        ]
      }
    }
  }
}

Responses​

{
  "201": {
    "description": "Success",
    "content": {
      "application/json": {
        "schema": {
          "type": "object"
        }
      }
    }
  },
  "400": {
    "description": "Validation error",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Error"
        }
      }
    }
  },
  "401": {
    "description": "Missing/expired/revoked credential",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Error"
        }
      }
    }
  },
  "403": {
    "description": "Insufficient role",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Error"
        }
      }
    }
  },
  "404": {
    "description": "Not found",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Error"
        }
      }
    }
  },
  "409": {
    "description": "State or idempotency conflict",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Error"
        }
      }
    }
  },
  "413": {
    "description": "Body too large",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Error"
        }
      }
    }
  },
  "415": {
    "description": "Unsupported media type",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Error"
        }
      }
    }
  },
  "429": {
    "description": "Request budget exhausted; respect Retry-After",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Error"
        }
      }
    },
    "headers": {
      "Retry-After": {
        "schema": {
          "type": "integer",
          "minimum": 1
        },
        "description": "Seconds until sufficient budget is expected; concurrent traffic may consume replenished capacity."
      }
    }
  },
  "500": {
    "description": "Internal error",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Error"
        }
      }
    }
  },
  "503": {
    "description": "Not configured",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Error"
        }
      }
    }
  }
}

References such as #/components/schemas/Asset resolve in shared schemas. Download the OpenAPI contract for client generation. This page is generated; it describes the implemented development API, not planned endpoints.