Invite a member

POST

/v1/members/invitations

curl --request POST \
  --url https://api.overwatch.weareheavy.dev/v1/members/invitations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "email": "editor@example.com", "role": "member", "siteIds": [ "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9" ], "canCrawl": true }'

• Production

Invite someone to the organization by email. Invitations expire after 48 hours. For the restricted member role, siteIds and canCrawl set the invitee’s initial grants (materialized when they accept); admins see every site, so the grants are ignored for admin. Session-only, owner/admin.

Authorizations

• BearerAuth

Request Body^required

Media typeapplication/json

object

email

required

string format: email

role

string

default: member

Allowed values: admin member

siteIds

Initial per-site allowlist (restricted member role only).

Array<string>

canCrawl

Initial crawl grant (restricted member role only).

boolean

Example

{
  "email": "editor@example.com",
  "role": "member",
  "siteIds": [
    "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9"
  ],
  "canCrawl": true
}

Responses

201

The invitation was created and emailed.

Media typeapplication/json

object

invitation

required

The created invitation, as returned by the auth layer.

object

Example^generated

{
  "invitation": {}
}

400

email is missing, or the auth layer rejected the invitation.

Media typeapplication/json

object

error

required

A human-readable error message.

string

Example

{
  "error": "email is required"
}

401

Missing or invalid credentials.

Media typeapplication/json

object

error

required

A human-readable error message.

string

Example

{
  "error": "invalid api key"
}

403

A dashboard session is required (API-key callers are rejected), or the session’s role does not allow this action.

Media typeapplication/json

object

error

required

A human-readable error message.

string

Example

{
  "error": "a dashboard session is required"
}