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

Invite a person

Invites a person by email with one or more scoped space roles.

POST/v1/spaces/{spaceId}/people
Authorization
AuthorizationBearer token · headerrequired

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

Path parameters
spaceIdstringrequired
Request body
requiredapplication/json
emailstring<email>required
matches ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
grantsobject[]required
min items 1 · max items 32
Show properties
Array of object
scopestringrequired
min length 1 · max length 1024
rolestringrequired
Allowed:viewercommentereditormanager
targetobject
default: {"kind":"live"}
Show properties
One of:
object
kindstringrequired
object
kindstringrequired
versionIdstringrequired
min length 1 · max length 255
object
kindstringrequired
branchstringrequired
min length 1 · max length 255
object
kindstringrequired
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
min length 1
spaceIdstringrequired
min length 1
displayNamestringrequired
min length 1 · max length 160
emailstring<email> | nullrequired
Show properties
Any of:
string<email>
string<email>
null
null
statusstringrequired
Allowed:pendingacceptedrevoked
grantsobject[]required
Show properties
Array of object
idstringrequired
min length 1
scopestringrequired
min length 1 · max length 1024
rolestringrequired
Allowed:viewercommentereditormanager
targetobjectrequired
Show properties
One of:
object
kindstringrequired
object
kindstringrequired
versionIdstringrequired
min length 1 · max length 255
object
kindstringrequired
branchstringrequired
min length 1 · max length 255
object
kindstringrequired
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))$
revokedAtstring<date-time> | nullrequired
Show properties
Any of:
string<date-time>
string<date-time>
null
null
invitedBystring | nullrequired
inviteExpiresAtstring<date-time> | nullrequired
Show properties
Any of:
string<date-time>
string<date-time>
null
null
acceptedAtstring<date-time> | nullrequired
Show properties
Any of:
string<date-time>
string<date-time>
null
null
revokedAtstring<date-time> | nullrequired
Show properties
Any of:
string<date-time>
string<date-time>
null
null
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))$
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
Parameters
Bodyapplication/json
Request
curl -X POST 'https://api.spacefast.com/v1/spaces/string/people' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "user@example.com",
  "grants": [
    {
      "scope": "string",
      "role": "viewer",
      "target": {
        "kind": "live"
      }
    }
  ]
}'
Response
{
  "$schema": "http://example.com",
  "data": {
    "id": "string",
    "spaceId": "string",
    "displayName": "string",
    "email": "user@example.com",
    "status": "pending",
    "grants": [
      {
        "id": "string",
        "scope": "string",
        "role": "viewer",
        "target": {
          "kind": "live"
        },
        "createdAt": "2019-08-24T14:15:22Z",
        "revokedAt": "2019-08-24T14:15:22Z"
      }
    ],
    "invitedBy": "string",
    "inviteExpiresAt": "2019-08-24T14:15:22Z",
    "acceptedAt": "2019-08-24T14:15:22Z",
    "revokedAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z"
  }
}