Skip Navigation Links

Invite Codes

List async invite-code batches

Requires authentication via bearer.

Returns the async invite-code batches that the actor can read, newest first.

Access: an actor that holds the INVITE_CODES MANAGE permission on the tenant's root user group sees every batch of the tenant. Every other actor sees only the batches that they created. An actor with no readable batch receives 200 and an empty array.

Progress counters: info repeats the counters of GET .../async-batch/{async_batch_id} and aggregates them the same way, so a row here and the single-batch endpoint always agree on state and counts.

Pagination: offset based, because the batch overview needs a page count and a total element count. Both sort keys, created_at and total, are immutable, so a sequence of pages neither repeats nor misses a row. The state filter is the one exception, see below.

Embedding: set embed=INITIATOR to resolve the user who triggered each batch into its initiator field, and embed=USER_GROUPS to resolve the groups each batch's request named into selection.user_groups[].user_group; titles follow Accept-Language.

Retention: batches and their items stay listed indefinitely. The sealed artifacts that SUCCESS items link to are deleted 24 to 48 hours after generation; state and counters are unaffected.

Query Params

page_number integer

requested page for offset based pagination. Refer to our general "pagination" concept for more information.

page_limit integer

The maximum number of items to be contained in the response array. Refer to our general "pagination" concept for more information.

sort string[]

Sort options for the async invite-code batch list:

  • CREATED_AT_ASC/DESC: sort by the time the batch was triggered.
  • TOTAL_ASC/DESC: sort by the number of items in the batch.
state string[]

Lifecycle state of a batch execution.

  • PENDING: accepted, not yet started.
  • IN_PROGRESS: items are being processed.
  • COMPLETED: every item reached a terminal state, also when every item is FAILURE; read info.failure for the outcome.
  • FAILED: a system fault stopped processing before every item ran (see error). Not produced today: this endpoint derives the state from its items.
created_by string[]

Unique identifier of a user.

embed string[]

Options for embedding additional data into the async invite-code batch list:

  • INITIATOR: embeds the user who triggered the batch into the initiator field of each batch.
  • USER_GROUPS: embeds every group a batch's request named into the user_group field of its selection.user_groups entries.

Headers

Accept-Language string

The preferred language used when returning localized strings.

Response Body

200 OK

Error Codes

  • FEATURE_DISABLED
  • PERMISSION_MISSING

Trigger async invite-code batch

Requires authentication via bearer.

Enqueues an asynchronous batch that generates invite codes for the given users.

Returns 202 Accepted immediately with target and status, the resource path of the created execution (its id is target_info.id); poll target for progress and GET .../async-batch/{async_batch_id}/items for per-item results.

Whole-request failures fail fast with a 4xx Problem — a batch doomed for every item (cap exceeded, malformed body such as an items entry named twice, tenant-wide precondition such as the feature being disabled or an out-of-range expiration_minutes) is never enqueued.

Per-user outcomes during generation are not errors here — users that are skipped or fail while their code is generated surface as items with state SKIPPED/FAILURE, not as a 4xx. Who may be named is checked up front, see User groups below.

Entitlement follows the user count. A request naming one user needs invite codes enabled for the tenant. A request naming more than one user also needs bulk invite codes enabled. Either missing yields 403 FEATURE_DISABLED.

User groups. Any USER_GROUP entry needs bulk invite codes enabled, whatever its member count. Each named group must be an active CUSTOM group the actor holds INVITE_CODES:MANAGE on, as its create_invite_code_batch action shows; if one is not, the whole request fails with 403 PERMISSION_MISSING and nothing is stored. The batch holds the union of the members of all named groups and the USER entries, each user once — also when a parent group is named together with one of its sub-groups, or a user is assigned to two named groups, or a user is named both as USER and through a group. A USER_GROUP entry with include_sub_groups extends to its active sub-groups at every depth; the flag is set per entry, so one group can take its sub-groups and another not. From the groups, members the actor cannot manage, deleted users, users whose type cannot hold a code and the actor are left out. Every USER entry must name a user the actor may manage; if any one of them is unknown, deleted, of a type that cannot hold a code, the actor, or otherwise unmanageable, the whole request fails with 403 PERMISSION_MISSING and nothing is stored. A batch has no limit on the number of users. If items holds no USER entry and the groups resolve to no user the actor may manage, the request fails with ASYNC_BATCH_EMPTY_SELECTION.

Request Body

output objectrequired

The output a batch produces. A batch is always delivered as sealed files; channels lists them, and every SUCCESS item carries one artifact per channel in this order.

skip_active_invite_codes boolean

When true (default), users that already have an active invite code are skipped (item state SKIPPED) instead of having it revoked and replaced.

skip_activated_users boolean

When true (default), users that are already activated are skipped (item state SKIPPED).

expiration_minutes integer

Minutes until each generated code expires. Same field and unit as the single-user CreateInviteCodeRequest. Out-of-range values reject the whole request with INVALID_EXPIRATION; the Problem detail names the requested value, the allowed range and the default.

items object[]

One entry of items; type says what id refers to.

recipient_public_key stringrequired

The recipient public key that encrypts this batch's invite codes. The value is self-describing: its type is differentiated by the key prefix (an age1… value selects age X25519), so further key types can be added later without a schema change. An unsupported key type is rejected with UNSUPPORTED_RECIPIENT_KEY_TYPE.

Response Body

202 Accepted

Error Codes

  • FEATURE_DISABLED
  • INVALID_EXPIRATION
  • ASYNC_BATCH_DUPLICATE_ITEMS
  • ASYNC_BATCH_SINGLE_REQUIRES_ONE_USER
  • UNSUPPORTED_RECIPIENT_KEY_TYPE
  • INVALID_TIME_ZONE
  • ASYNC_BATCH_DUPLICATE_CHANNELS
  • INVALID_DOWNLOAD_URL
  • ASYNC_BATCH_EMPTY_SELECTION
  • ASYNC_BATCH_TOO_MANY_ITEMS
  • PERMISSION_MISSING
  • INVALID_SUPPORT_CONTACT
  • INVALID_INCLUDE_SUB_GROUPS

Poll async invite-code batch execution

Requires authentication via bearer.

Returns the execution state and progress counters for a batch.

Readable immediately after the triggering 202 (no 404-until-terminal). While the execution is not terminal (state is PENDING or IN_PROGRESS) the response includes a Retry-After header hinting when to poll next.

Entitlement: a batch with one user needs invite codes enabled for the tenant; a batch with more than one user also needs bulk invite codes enabled.

Embedding: set embed=USER_GROUPS to resolve the groups the request named into selection.user_groups[].user_group; titles follow Accept-Language.

Path Params

async_batch_id stringrequired

Identifier of the async batch execution, as returned in target_info.id.

Query Params

embed string[]

Options for embedding additional data into the async invite-code batch execution:

  • USER_GROUPS: embeds every group the request named into the user_group field of its selection.user_groups entry.

Headers

Accept-Language string

The preferred language used when returning localized strings.

Response Body

200 OK

Error Codes

  • FEATURE_DISABLED
  • PERMISSION_MISSING
  • ASYNC_BATCH_NOT_FOUND

List async invite-code batch item results

Requires authentication via bearer.

Returns the per-user results of a batch, cursor-paginated and optionally filtered by item state. Readable from the triggering 202 on; each read shows the live state of every item. The item set is fixed, so only state, body, reason and error change while the batch runs.

Filtering: repeat state to narrow to specific outcomes; the filter must stay constant across pages of one pagination sequence.

Embedding: set embed=USER to resolve the user of every item of the page into its user field.

Entitlement: a batch with one user needs invite codes enabled for the tenant; a batch with more than one user also needs bulk invite codes enabled.

Path Params

async_batch_id stringrequired

Identifier of the async batch execution, as returned in target_info.id.

Query Params

state string[]

Per-item outcome.

  • PENDING: not yet processed.
  • SUCCESS: an invite code was generated.
  • SKIPPED: skipped by a business rule, see reason.
  • FAILURE: processing failed for this user (see error).
page_cursor string

A cursor pointing to the first item to be contained in the response array. Refer to our general "pagination" concept for more information.

page_limit integer

The maximum number of items to be contained in the response array. Refer to our general "pagination" concept for more information.

embed string[]

Options for embedding additional data into the async invite-code batch item list:

  • USER: embeds the user the item generates a code for into the user field of each item.

Response Body

200 OK

Error Codes

  • FEATURE_DISABLED
  • PERMISSION_MISSING
  • ASYNC_BATCH_NOT_FOUND