Invitations tools

• invitations_accept: Accept an invitation
• invitations_create: Invite someone to the organization
• invitations_list: List invitations
• invitations_lookup: Look up an invitation
• invitations_revoke: Revoke an invitation

invitations_accept#

Accept an invitation. Operation invitations.accept · Platform level · permission account:write · risk tier write · since M1

Accepts an invitation: you become a member of the organization with the invitation's role and scope. You must be signed in with the address the invitation was sent to, and the invitation must be pending (not accepted, revoked or older than 7 days). Live-mode access follows the role (developers start without it). Returns the new membership and the organization, whose console is /console/{slug}.

Who can call it: any signed-in user holding the token from the invitation link.

Annotations: readOnlyHint: false · destructiveHint: false · idempotentHint: false · openWorldHint: false

Arguments#

• Idempotency: the result returns the idempotency_key used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
• Dry run: supported. dry_run: true checks permissions and rules and computes the result, then rolls everything back.

Errors#

• validation_failed: The token is malformed.
• invitation_invalid: No invitation has this token, or what it grants no longer exists.
• invitation_expired: The invitation is older than 7 days.
• invitation_revoked: The invitation was revoked.
• invitation_already_accepted: The invitation was already accepted.
• invitation_email_mismatch: You're signed in with another address than the invited one.
• membership_exists: You already have a membership at this scope.
• entitlement_required: The organization's members.max is reached.
• version_conflict: The invitation changed at the same time (for example, it was revoked).
• permission_denied: The caller isn't a signed-in user.

Example#

Accept an invitation to a brand

Arguments:

{
  "token": "ExampleOnlyNotARealInvitationToken000000000",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}

Result output:

{
  "membership": {
    "id": "mem_01m4tx5nj8emwbyf7y9vcf47x6",
    "object": "membership",
    "orgId": "org_01m4tx5nj7ekd958x53w4bntcg",
    "userId": "usr_01m4tx5nj8emwbyf7y9vcf47xb",
    "role": "developer",
    "scope": {
      "type": "brand",
      "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4"
    },
    "livemodeAccess": false,
    "invitedBy": "usr_01m4tx5nj8emwbyf7y9vcf47xa",
    "user": {
      "email": "dev@acme.example",
      "name": "Dana Developer"
    },
    "createdAt": "2026-10-13T12:00:00.000Z",
    "updatedAt": "2026-10-13T12:00:00.000Z"
  },
  "organization": {
    "id": "org_01m4tx5nj7ekd958x53w4bntcg",
    "slug": "acme",
    "name": "Acme"
  }
}

invitations_create#

Invite someone to the organization. Operation invitations.create · Organization level · permission members:admin · risk tier security · since M1

Invites a person by email with a role and a scope (the whole organization, one legal entity or one brand). They accept by signing in with that address and opening the link; the invitation expires after 7 days. Live-mode access follows the role (developers start without it; change it after they join).

Ownrecord emails the invitation link to the address right after the change is saved. The response also contains the invitation token (link: /console/invitations/{token}), once: only a hash is stored.

You can't invite anyone with more access than you have. A pending invitation reserves a seat: members plus pending invitations count against the plan's members.max. Needs members:admin and a signed-in member (the invitation says who invited; API keys can't invite). A security-tier change.

Annotations: readOnlyHint: false · destructiveHint: false · idempotentHint: false · openWorldHint: false

Arguments#

• Idempotency: the result returns the idempotency_key used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
• Dry run: supported. dry_run: true checks permissions and rules and computes the result, then rolls everything back.

Errors#

• validation_failed: The email, role or scope is malformed, or the role isn't allowed at the scope.
• resource_not_found: The scope's entity or brand doesn't exist in the organization.
• role_not_grantable: The role and scope give more access than you have.
• membership_exists: The person is already a member at this scope.
• invitation_exists: The person already has a pending invitation at this scope.
• entitlement_required: Members and pending invitations already fill members.max.
• permission_denied: You can't manage members of this organization, or the caller is an API key.

Example#

Invite a finance colleague for one entity

Arguments:

{
  "email": "finance@acme.example",
  "role": "finance",
  "scope": {
    "type": "entity",
    "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2"
  },
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}

Result output:

{
  "id": "invt_01m4tx5nj8emwbyf7y9vcf47x8",
  "object": "invitation",
  "orgId": "org_01m4tx5nj7ekd958x53w4bntcg",
  "email": "finance@acme.example",
  "role": "finance",
  "scope": {
    "type": "entity",
    "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2"
  },
  "status": "pending",
  "expiresAt": "2026-10-20T12:00:00.000Z",
  "invitedBy": "usr_01m4tx5nj8emwbyf7y9vcf47xa",
  "acceptedAt": null,
  "revokedAt": null,
  "createdAt": "2026-10-13T12:00:00.000Z",
  "token": "ExampleOnlyNotARealInvitationToken000000000"
}

invitations_list#

List invitations. Operation invitations.list · Organization level · permission members:read · risk tier read · since M1

Lists the organization's invitations, newest first, with their status: pending, accepted, revoked or expired (invitations work for 7 days). Filter with status, e.g. pending for the invitations still waiting for an answer. Tokens are never returned. Paginate with limit and starting_after.

Needs members:read (organization owners and admins, or an org management key).

Annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Arguments#

• Read-only: changes nothing; idempotency_key is ignored.

Errors#

• validation_failed: A filter or pagination value is malformed.
• permission_denied: You can't see this organization's members.

Examples#

Pending invitations

Arguments:

{
  "status": "pending"
}

Result output:

{
  "object": "list",
  "data": [
    {
      "id": "invt_01m4tx5nj8emwbyf7y9vcf47x8",
      "object": "invitation",
      "orgId": "org_01m4tx5nj7ekd958x53w4bntcg",
      "email": "finance@acme.example",
      "role": "finance",
      "scope": {
        "type": "entity",
        "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2"
      },
      "status": "pending",
      "expiresAt": "2026-10-20T12:00:00.000Z",
      "invitedBy": "usr_01m4tx5nj8emwbyf7y9vcf47xa",
      "acceptedAt": null,
      "revokedAt": null,
      "createdAt": "2026-10-13T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Everything, two per page

Arguments:

{
  "limit": 2
}

Result output:

{
  "object": "list",
  "data": [
    {
      "id": "invt_01m4tx5nj8emwbyf7y9vcf47x8",
      "object": "invitation",
      "orgId": "org_01m4tx5nj7ekd958x53w4bntcg",
      "email": "finance@acme.example",
      "role": "finance",
      "scope": {
        "type": "entity",
        "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2"
      },
      "status": "pending",
      "expiresAt": "2026-10-20T12:00:00.000Z",
      "invitedBy": "usr_01m4tx5nj8emwbyf7y9vcf47xa",
      "acceptedAt": null,
      "revokedAt": null,
      "createdAt": "2026-10-13T12:00:00.000Z"
    },
    {
      "id": "invt_01m4tx5nj8emwbyf7y9vcf47x9",
      "object": "invitation",
      "orgId": "org_01m4tx5nj7ekd958x53w4bntcg",
      "email": "dev@acme.example",
      "role": "developer",
      "scope": {
        "type": "brand",
        "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4"
      },
      "status": "accepted",
      "expiresAt": "2026-10-20T12:00:00.000Z",
      "invitedBy": "usr_01m4tx5nj8emwbyf7y9vcf47xa",
      "acceptedAt": "2026-10-14T09:30:00.000Z",
      "revokedAt": null,
      "createdAt": "2026-10-13T12:00:00.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "invt_01m4tx5nj8emwbyf7y9vcf47x9"
}

invitations_lookup#

Look up an invitation. Operation invitations.lookup · Platform level · permission account:read · risk tier read · since M1

Shows what an invitation link offers: the organization, the role and scope, who invited, when it expires and its status. The invited address is shown in full only when you're signed in with it.

Who can call it: any signed-in user holding the token from the invitation link.

Annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Arguments#

• Read-only: changes nothing; idempotency_key is ignored.

Errors#

• validation_failed: The token is malformed.
• invitation_invalid: No invitation has this token.
• permission_denied: The caller isn't a signed-in user.

Example#

A pending invitation for the signed-in address

Arguments:

{
  "token": "ExampleOnlyNotARealInvitationToken000000000"
}

Result output:

{
  "object": "invitation_preview",
  "status": "pending",
  "organization": {
    "name": "Acme",
    "slug": "acme"
  },
  "role": "finance",
  "scope": {
    "type": "entity",
    "name": "Acme Digital d.o.o."
  },
  "email": "finance@acme.example",
  "emailMatches": true,
  "invitedBy": "Olivia Owner",
  "expiresAt": "2026-10-20T12:00:00.000Z"
}

invitations_revoke#

Revoke an invitation. Operation invitations.revoke · Organization level · permission members:admin · risk tier security · since M1

Revokes a pending invitation: its link stops working at once. Accepted, revoked and expired invitations can't be revoked (invitation_not_pending). Give a reason: it goes to the audit log.

Like members, you can only revoke invitations you could have sent (an admin can't revoke an invitation to become an owner). Needs members:admin; a security-tier change.

Annotations: readOnlyHint: false · destructiveHint: true · idempotentHint: false · openWorldHint: false

Arguments#

• Idempotency: the result returns the idempotency_key used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
• Dry run: supported. dry_run: true checks permissions and rules and computes the result, then rolls everything back.

Errors#

• resource_not_found: No such invitation in this organization.
• invitation_not_pending: The invitation was already accepted, revoked or has expired.
• role_not_grantable: The invitation grants more access than you have.
• version_conflict: The invitation changed at the same time (for example, it was accepted).
• permission_denied: You can't manage members of this organization.

Example#

Revoke an invitation sent to the wrong address

Arguments:

{
  "id": "invt_01m4tx5nj8emwbyf7y9vcf47x8",
  "reason": "Sent to the wrong address",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}

Result output:

{
  "id": "invt_01m4tx5nj8emwbyf7y9vcf47x8",
  "object": "invitation",
  "orgId": "org_01m4tx5nj7ekd958x53w4bntcg",
  "email": "finance@acme.example",
  "role": "finance",
  "scope": {
    "type": "entity",
    "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2"
  },
  "status": "revoked",
  "expiresAt": "2026-10-20T12:00:00.000Z",
  "invitedBy": "usr_01m4tx5nj8emwbyf7y9vcf47xa",
  "acceptedAt": null,
  "revokedAt": "2026-10-14T09:30:00.000Z",
  "createdAt": "2026-10-13T12:00:00.000Z"
}