Endpoint Overview
/api/admin/invite-codes/v4/async-batch/api/admin/invite-codes/v4/async-batch/api/admin/invite-codes/v4/async-batch/{async_batch_id}/api/admin/invite-codes/v4/async-batch/{async_batch_id}/items/api/admin/invite-codes/v4/async-batch/api/admin/invite-codes/v4/async-batch/api/admin/invite-codes/v4/async-batch/{async_batch_id}/api/admin/invite-codes/v4/async-batch/{async_batch_id}/itemsReturns 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.
page_number integerrequested page for offset based pagination. Refer to our general "pagination" concept for more information.
page_limit integerThe 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.Accept-Language stringThe preferred language used when returning localized strings.
200 OKEnqueues 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.
output objectrequiredThe 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 booleanWhen 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 booleanWhen true (default), users that are already activated are skipped (item state SKIPPED).
expiration_minutes integerMinutes 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 stringrequiredThe 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.
202 AcceptedReturns 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.
async_batch_id stringrequiredIdentifier of the async batch execution, as returned in target_info.id.
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.Accept-Language stringThe preferred language used when returning localized strings.
200 OKReturns 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.
async_batch_id stringrequiredIdentifier of the async batch execution, as returned in target_info.id.
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 stringA cursor pointing to the first item to be contained in the response array. Refer to our general "pagination" concept for more information.
page_limit integerThe 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.200 OK