Glossary¶

AppGantry-specific terminology. If a term is used in the product or in this documentation and isn't here, it should be — tell us.

People and identity¶

Developer — a person with an AppGantry account. One human, one account. Developers move between organizations; the account belongs to the person.

Tester — someone who installs your builds but doesn't develop them. Testers hold grants, not roles, and see only what they've been granted.

Member — a developer who belongs to an organization or a project, with a role.

Operator — AppGantry staff. Some workflows, such as final BYOSA activation, are completed with an operator's help.

Interactive sign-in — a request authenticated by a developer who signed in themselves, carrying a short-lived access token rather than a personal or project access token. A handful of surfaces — account settings, account security, token management, organization creation, SSO and storage configuration, invitation acceptance, your own audit feed — accept nothing else, and refuse a long-lived token with 403 whatever its scope. See Where long-lived tokens are refused.

Organization and project¶

Organization — the top-level billing, membership, and audit boundary. Everything lives inside one. Your invoice is per organization. A developer can belong to up to 5.

Project — one app you distribute. Belongs to exactly one organization, targets exactly one platform, chosen at creation. Up to 50 per organization.

Platform — what the project's builds run on: iOS, Android, tvOS, watchOS, visionOS, or Wear OS. A platform family groups these as Apple or Android, which is what determines the install mechanism.

Builds and distribution¶

Build — one uploaded artifact plus its metadata: version name, build number, platform, release notes, checksum, uploader. Apple builds are .ipa; Android builds are .apk.

Pending upload — a reserved, not-yet-completed upload. Holds a signed URL valid for 1 hour. Becomes a build when you complete it. At most 25 per project.

Channel — a named distribution stream inside a project: Internal, Beta, Production, whatever you like. Holds a sequence of releases. Available on all plans.

Release — a build published into a channel. Testers follow channels, not builds, so publishing a release reaches everyone on the channel.

Publish — two different actions share this verb, and only one of them works:

Publish to a channel — turning a build into a release so your testers can install it. This is the everyday meaning, it works, and it is what the web app's Channels → Releases → Publish a build action does.
Publish to a store — submitting a build to App Store Connect, Google Play, or Microsoft Intune through a store connection. This creates a publish job and is not operational: every job ends failed and no artifact reaches the provider.

When a page says "publishing is not operational", it always means the second one.

Current release — the release a channel is presently serving for a given platform. Changed by publishing, by rolling back, or by disabling.

Mandatory release — a release marked as required. The in-app updates SDK reports this so your app can insist the user updates.

Rollback — stepping a channel's current release back to the previous one, without deleting anything.

Revoked build — a build withdrawn from distribution. Still listed, still stored, no longer downloadable.

Retention — how long builds are kept before automatic deletion. 30 days by default on Team, 365 on Business.

Over-the-air (OTA) install — installing an Apple build directly onto a device from Safari, without the App Store. The capability that authorizes it lasts about 15 minutes and works only on the device itself.

Direct install — the Android equivalent: download the .apk and install it, with "install from unknown sources" allowed for the browser.

Install link — a link that starts an install. Personal to a tester, or anonymous if the channel is public.

Public channel — a channel whose current release can be installed by anyone with the link, without signing in. Turning it off revokes the link immediately.

Testers¶

Grant — a tester's access, attached at organization, project, or channel level. Organization grants reach every channel in the organization; channel grants reach one channel.

Tester group — a named set of testers plus a set of grants. Adding someone to the group gives them the group's grants; removing them takes them away.

Pending tester — an organization or project tester grant with nobody to attach to yet. Which way an add goes is settled at the moment it is made, by whether any AppGantry account holds the address: if no account at all holds it, the grant is pending. An account that has not verified its email still takes the grant there and then, so that tester is active immediately — verifying is what that person needs before they can sign in and use it, not before the grant lands. Nothing is sent for them to accept: there is no token, no link, and no accept step. A grant that is pending attaches on its own once somebody signs up with that address and verifies it, and it waits indefinitely until then. A channel invitation is the one that has to be accepted, and it is a separate, 10-minute link.

Tester portal — the part of the web app testers see: the apps and channels they've been granted, and install buttons.

Devices¶

Device — a registered test device. Apple ad-hoc distribution requires the device's identifier to be in the provisioning profile the build was signed with.

UDID — the Unique Device Identifier Apple uses to name one iPhone, iPad, or other Apple device in a provisioning profile. Collecting it is the entire point of the enrollment link; registering it with Apple is what lets an ad-hoc build install. Android has no equivalent step.

Enrollment link — a link a tester opens on the device to register it. Valid for 1 hour, and also shown as a QR code so a device sitting next to you can scan it.

Store connection — stored credentials for an app store provider. Today it validates and holds those credentials and, for Apple, registers test devices. Publishing builds through it is a future capability and is not operational.

Publish job — a request to push a build to a connected store. The request is accepted and the job is tracked, but no provider submission is available, so a job currently ends failed. The status contract it is defined against — pending → processing → completed or failed — is what will apply once store publishing ships. Not to be confused with publishing to a channel.

Storage¶

Hosted storage — AppGantry's own storage. The default, metered per-MB across upload, storage, and download.

BYOSA — Bring Your Own Storage Account. Artifacts live in your Azure storage account and the per-MB meters don't apply. Business only. See BYOSA.

Container — under BYOSA, the single storage container that holds the organization's artifacts. AppGantry writes nowhere else.

Onboarding request — a BYOSA request you submit and AppGantry reviews. Moves through pending, validated, approving, approved, or the failure states rejected and validation failed.

Signed URL — a time-limited URL that authorizes exactly one transfer to or from storage. Both uploads and downloads use them; there are no permanent artifact URLs.

Billing¶

Platform fee — the flat monthly fee per organization.

Meter — one of the three usage counters: storage in MB-months, upload in MB, download in MB. Not applied to BYOSA organizations.

Billing period — a calendar month, UTC.

Pre-paid balance — the credit a Team organization holds. Usage draws it down; at zero, byte movement returns HTTP 402.

Spend cap — a ceiling on metered usage for the billing period, made up of your own self-limit and an account ceiling. The lower of the two applies.

Reservation — the projected cost briefly held against your balance when an upload or download is admitted, so concurrent requests can't collectively overspend. Releases itself shortly if unused.

Write lock — an organization state that blocks changes while leaving data readable. Reported as HTTP 402 with a lock_reason of grace, awaiting_payment, or suspended. A payment still being retried is not a write lock. See Errors → 402.

Trial — a time-limited, no-card start on Team, with usage caps and a small starter credit. When the timer runs out, writes are locked with trial_ended and a lock_reason of grace; when the starter credit runs out first, the refusal is prepaid_credit_exhausted.

Credentials¶

Access token — a short-lived (10 minute) signed token carrying developer identity.

Refresh token — a 30-day, single-use token that mints a new access token. Presenting one twice revokes the whole session family.

Session — one sign-in on one device. Listable and individually revocable.

Personal access token (PAT) — a long-lived credential bound to a developer and one organization, carrying scopes. Prefix ag_pat_.

Project access token — a long-lived credential owned by a project rather than a person, carrying a capped project role. Prefix ag_prj_. The right credential for CI.

Passkey — a phishing-resistant credential that can replace your password or act as a second factor. Up to 20 per developer.

TOTP — time-based one-time codes from an authenticator app.

Recovery code — a single-use code for signing in when your second factor is unavailable. Shown once; regenerating invalidates the old set.

SSO — signing in through your own identity provider using SAML. Business only.

SDK app key / app secret — the public identifier and the shown-once secret used by the in-app updates SDK. The secret enrolls an install; the resulting update token lasts 30 days.

Permissions¶

Role — what a member can do. Organization roles are Read, Editor, Manager, Admin. Project roles are Read, Read + Download, Read + Download + Upload, Maintainer, Admin.

Scope — what a personal access token may do: Read, Upload Build, Revoke Build, Manage Releases, Manage Testers, Edit Project, plus the composite ALL. Scopes intersect with your own permissions rather than adding to them.

API mechanics¶

Cursor — the opaque pagination token returned as next_cursor. Pass it back as ?cursor=. Never parse or construct one.

Page size — ?limit=, defaulting to 100 and capped at 1000.

Error envelope — the flat {error, message, details} shape almost every error uses. Match on error. Request validation uses it too: 400 with error: "validation_error" and the failing fields under details.errors. The exception is the two not-configured 404s, which answer a bare {"error": …}. See Errors.

Two-phase upload — initiate, PUT the bytes to a signed URL, complete with the SHA-256. Artifact bytes never pass through the API. See Uploading a build.

Idempotency — the property that repeating a request has the same effect as making it once. AppGantry has no idempotency-key header, so the API cannot collapse your retry onto the original attempt: a retried write may do the work twice. Read the resource back before retrying a write that may have landed. In the other direction, webhook deliveries are at-least-once, so your receiver has to be idempotent — key on the delivery identifier, which is stable across retries. See Idempotency and retries.

Feature flag — a named boolean the platform can switch without a deploy, resolved per organization and readable through the Feature Flags surface. It is a diagnostic read, not a control: there is no operation for changing one, archived flags are omitted from the response, and a key you do not see is off. Distinct from a plan gate (what your tier includes) and from an environment gate (what a deployment has switched on) — see Feature availability.

Observability¶

Audit feed — the append-only record of state-changing actions, per organization and per developer. See Audit events.

Webhook — an HTTP callback for release and build events. Delivery is at-least-once, unordered, and best-effort. See The event catalogue.

Fan-out — the step that turns one action into a delivery per matching subscription. It happens after the action has committed and been audited, and never blocks it, so an upload or release can succeed with nothing delivered. That is why the audit feed is the record and a webhook is only a signal.

Dead-lettered — the terminal state of a webhook delivery that failed its last attempt. AppGantry retries a failing delivery on a widening backoff for up to about 16 hours across 10 attempts, then gives up: the delivery is marked dead-lettered, kept in the delivery log, and never re-sent. Fix the receiver and prove it with a test delivery; there is no replay.

Delivery log — the record of webhook delivery attempts and their outcomes. Doesn't echo payloads.

Analytics — download and install counts for channels and releases. Distribution reach, not product usage.