--- title: "share_space" description: "Generated reference for the management action share_space: its description, access metadata, payload contract, and registration status." slug: /reference/actions/share-space order: 75 visibility: public redirects_from: ["/reference/actions/share-issue-space"] --- # share\_space Generated automatically from the [published contract sources](/cloud/reference/about/#contract-sources). A script calls this action over HTTPS at `POST https://turnzero.ai/api/v1/actions/share_space`, with a bearer credential and the action's payload as the JSON body. An MCP connection lists this action as the tool `tztrack_share_space`. **Build metadata:** Registered in this build. Registration describes the default dispatcher in this build. It does not guarantee that a caller has the required credential or grant, that a tool is listed for that connection, or that the required service is configured. ## Contract description Add or remove a member of an issue space you own; pass `space` and either `add` or `remove`\. Use `list_space_members` to read membership without changing it\. `add` takes an existing account's sign\-in email and a `level` of `report`, `contribute`, or `owner`, defaulting to `contribute`; a repeat changes that member's level\. `remove` takes the member's email\. An address with no signed\-in account is refused `no_such_account`, with nothing kept for later\. A member works the space at its level and cannot share it\. The answer lists the members; `users` counts them plus you, and `tztrack_tier` gives your account's tier\. Your account needs tzTrack, which every account has\. ## More about this action The answer also gives your account's tzTrack tier after the call, `tztrack_tier`, and the end of its payment grace, `tztrack_grace_end`, null where none was written, so an `add` that starts a grace says so\. ## Access and action metadata ```json { "name": "share_space", "resource": "account", "tier": "reversible", "surface": "tztrack", "product": "tztrack", "admits": [ "tztrack", "device_sign_in" ], "summary": "Share one issue space the account owns with other accounts, each a member at one level. `space` picks the space. `add` gives an existing account by the email address it signs in with, and `level` the level it works the space at through `relay_issue_act`, `report`, `contribute`, or `owner`, `contribute` where absent; a standing member's level moves. `remove` gives a member by that address. With neither the call is refused `invalid_request`, pointing to `list_space_members`. An address no account signed in with is refused `no_such_account`, and nothing is kept for a later sign-in. A space the account does not own, one shared with it among them, is refused `space_not_owned`; a member never shares, and the feedback actions stay the owner's. An account that does not hold tzTrack is refused `blueprint_required` ahead of the form and the space's ownership. The answer carries the members, each with its account, address, level, and the instant it was added, and `users`, the members plus the owner, and the owner's tzTrack tier and payment grace's end after the call, `tztrack_tier` and `tztrack_grace_end`, so an `add` that starts a grace says so. Registered while the issue service's origin is configured.", "annotations": { "readOnlyHint": false, "destructiveHint": false, "openWorldHint": false, "idempotentHint": true } } ``` ## MCP catalog entry ```json { "name": "share_space", "title": "Share issue space", "tier": "reversible", "scenario": "API-L0-20", "summary": "Add or remove a member of an issue space you own; pass `space` and either `add` or `remove`. Use `list_space_members` to read membership without changing it. `add` takes an existing account's sign-in email and a `level` of `report`, `contribute`, or `owner`, defaulting to `contribute`; a repeat changes that member's level. `remove` takes the member's email. An address with no signed-in account is refused `no_such_account`, with nothing kept for later.\n\nA member works the space at its level and cannot share it. The answer lists the members; `users` counts them plus you, and `tztrack_tier` gives your account's tier. Your account needs tzTrack, which every account has.", "owners": [ "ITS-L0-07", "ACB-L0-92" ] } ``` ## request | JSON pointer | Description and constraints | |---|---| | "" \(root\) | Type: object
Required fields: \["space"\] | | /properties/space | The space to share, a lower\-case UUID of a space your account owns\.

Type: string
Pattern: ^\[0\-9a\-f\]\{8\}\-\[0\-9a\-f\]\{4\}\-\[0\-9a\-f\]\{4\}\-\[0\-9a\-f\]\{4\}\-\[0\-9a\-f\]\{12\}$ | | /properties/add | The sign\-in email address of an existing account to add as a member, or whose level to move\. An address no account signed in with is refused `no_such_account`; nothing is kept for a later sign\-in\. Never beside `remove`\.

Type: string
Maximum length: 320 | | /properties/level | With `add`: the level the member works the space at through the relay, `contribute` where absent\. `owner` reaches every relayed act and makes nobody an owner: the space stays yours, and a member never shares it\.

Type: string
Allowed values: \["report","contribute","owner"\] | | /properties/remove | The sign\-in email address of the member to remove\. Never beside `add`\.

Type: string
Maximum length: 320 | ## response | JSON pointer | Description and constraints | |---|---| | "" \(root\) | Type: object
Required fields: \["contract\_version","space","members","users","tztrack\_tier","tztrack\_grace\_end"\] | | /properties/contract\_version | Required value: 1 | | /properties/reference | The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call's record row\. Quote it when you report the call\.

Type: string
Pattern: ^\[0\-9a\-f\]\{10\}$ | | /properties/space | The space shared\.

Type: string | | /properties/members | The members of the space after the call, oldest first; you, the owner, are not among them\.

Type: array | | /properties/members/items | Type: object
Required fields: \["account","address","level","added\_at"\] | | /properties/members/items/properties/account | The member's account identifier, the one its claims and its `person:` carry\.

Type: string | | /properties/members/items/properties/address | The sign\-in email address the member was added by\.

Type: string | | /properties/members/items/properties/level | Type: string
Allowed values: \["report","contribute","owner"\] | | /properties/members/items/properties/added\_at | The instant the member was added, or its level last moved\.

Type: string | | /properties/users | The members plus you\.

Type: integer
Minimum: 1 | | /properties/tztrack\_tier | Your account's tzTrack tier as the space's owner, after the call\. It is derived at the read, so an `add` that starts a payment grace says so\. It is `introductory` while tzTrack's introductory period runs; after it, `paid`, `grace` for an account that must pay inside its payment grace, `stopped` once that grace has ended, or `free`\.

Type: string
Allowed values: \["introductory","paid","grace","stopped","free"\] | | /properties/tztrack\_grace\_end | The end of your account's, the owner's, tzTrack payment grace, ISO 8601, where one was written, and null otherwise\. Past it, an account that must pay and reads no paid tier reads `stopped`\.

Type: \["string","null"\] | ## Complete payload contract ```json { "request": { "type": "object", "required": [ "space" ], "properties": { "space": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The space to share, a lower-case UUID of a space your account owns." }, "add": { "type": "string", "maxLength": 320, "description": "The sign-in email address of an existing account to add as a member, or whose level to move. An address no account signed in with is refused `no_such_account`; nothing is kept for a later sign-in. Never beside `remove`." }, "level": { "type": "string", "enum": [ "report", "contribute", "owner" ], "description": "With `add`: the level the member works the space at through the relay, `contribute` where absent. `owner` reaches every relayed act and makes nobody an owner: the space stays yours, and a member never shares it." }, "remove": { "type": "string", "maxLength": 320, "description": "The sign-in email address of the member to remove. Never beside `add`." } } }, "response": { "type": "object", "required": [ "contract_version", "space", "members", "users", "tztrack_tier", "tztrack_grace_end" ], "properties": { "contract_version": { "const": 1 }, "reference": { "type": "string", "pattern": "^[0-9a-f]{10}$", "description": "The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call's record row. Quote it when you report the call." }, "space": { "type": "string", "description": "The space shared." }, "members": { "type": "array", "items": { "type": "object", "required": [ "account", "address", "level", "added_at" ], "properties": { "account": { "type": "string", "description": "The member's account identifier, the one its claims and its `person:` carry." }, "address": { "type": "string", "description": "The sign-in email address the member was added by." }, "level": { "type": "string", "enum": [ "report", "contribute", "owner" ] }, "added_at": { "type": "string", "description": "The instant the member was added, or its level last moved." } } }, "description": "The members of the space after the call, oldest first; you, the owner, are not among them." }, "users": { "type": "integer", "minimum": 1, "description": "The members plus you." }, "tztrack_tier": { "type": "string", "enum": [ "introductory", "paid", "grace", "stopped", "free" ], "description": "Your account's tzTrack tier as the space's owner, after the call (ACB-L0-92). It is derived at the read, so an `add` that starts a payment grace says so. It is `introductory` while tzTrack's introductory period runs; after it, `paid`, `grace` for an account that must pay inside its payment grace, `stopped` once that grace has ended, or `free`." }, "tztrack_grace_end": { "type": [ "string", "null" ], "description": "The end of your account's, the owner's, tzTrack payment grace, ISO 8601, where one was written, and null otherwise (ACB-L0-92). Past it, an account that must pay and reads no paid tier reads `stopped`." } } } } ``` ## Shared contracts - [Refusals](/cloud/reference/refusals/): every refusal, by surface, with its cause and its remedy - [schemas/wire\_error\.schema\.json](/cloud/reference/sources/schemas/wire-error-schema/) - [schemas/wire\_errors\.json](/cloud/reference/sources/schemas/wire-errors/) - [schemas/action\_payloads\.json](/cloud/reference/sources/schemas/action-payloads/) (includes shared shapes) - [management\_api\_contract\.md](/cloud/reference/sources/management-api-contract/)