What happens if I don't include a field when updating a publication?

Any field not included in the request body will be reset to its default value. It's a full replacement, not a partial update.

What are the two APIs available for updating publications?

Applivery provides the Integrations API (for single-app updates using an App API Token) and the Workspace API (for workspace-level updates using a Service Account token).

When should I use the Integrations API to update a publication?

Use the Integrations API when updating publications within the scope of a single app, typically in CI/CD pipelines. It uses an App API Token for authentication.

When should I use the Workspace API to update a publication?

Use the Workspace API for workspace-level automation across multiple apps. It requires a Service Account token and explicit `organizationId` and `storeId` in the path.

How do I authenticate with the Integrations API?

Authenticate with the Integrations API using an App API Token in the `Authorization` header: `Authorization: Bearer `.

How do I authenticate with the Workspace API?

Authenticate with the Workspace API using a Service Account token in the `Authorization` header: `Authorization: Bearer `.

What HTTP method is used to update a publication?

A `PUT` request is used to update a publication using either the Integrations API or the Workspace API.

How do I restrict access to a publication to specific user groups?

Set the `security` parameter to `logged` and provide an array of group names in the `groups` parameter. Supports AND/OR logic for multiple groups.

Update Applivery Published Applications via API

Update the configuration of an existing publication. All updatable fields from the POST – Create a Published Application endpoint are supported here, including security mode, build filter, access control, visibility, branding overrides, and legal terms.

Warning

This is a full replacement (PUT), not a partial update (PATCH). Any field not included in the request body will be reset to its default value. Always retrieve the current publication state first and include all fields you want to preserve.

Applivery provides two separate APIs for updating publications, each requiring a different authentication credential.

Choosing the right API

	Integrations API	Workspace API
Designed for	Per-app CI/CD pipelines	Workspace-level automation across multiple apps
Authentication	App API Token (per-app)	Service Account token (workspace-level)
App context	Implicit — token is already scoped to an app	Explicit — `organizationId` and `storeId` required in the path
Typical users	Scripts that update a publication's build filter after a new upload	Platform engineers managing publications across multiple apps

Warning

Access to the different APIs might not be available in your current plan. Please check availability on our pricing page.

Integrations API

Use this endpoint when updating publications within the scope of a single app. Authentication uses an App API Token, scoped to the specific app.

To create an App API Token, see Apps API Authentication.

Endpoint

PUT https://api.applivery.io/v1/integrations/distributions/{publishedApplicationId}

Authentication

Authorization: Bearer <your_app_token>

Request format

application/json

Path parameters

Parameter	Type	Required	Description
`publishedApplicationId`	String	Yes	The unique identifier of the publication to update. E.g. `552ae3cfcb5abfc58d733b81`. Returned by POST – Create a Published Application and GET – List of Published Applications.

Parameters

Identity and Visibility

Parameter	Type	Description
`slug`	String	The URL-friendly identifier for this publication. Must be unique within the workspace. Changing the slug changes the publication URL — existing links will break.
`visibility`	String	Publication visibility. Allowed values: `active`, `inactive`, `unlisted`.

Security and Access Control

Parameter	Type	Description
`security`	String	Authentication mode. Allowed values: `public`, `password`, `logged`.
`password`	String	Required when `security` is `password`. The password users must enter to access the publication.
`groups`	Array	Restricts access to specific user groups. Supports AND/OR logic. Each inner array is an AND clause; each outer element is an OR clause. E.g. `[["group1","group2"],["group3"]]`. Only applies when `security` is `logged`.
`activateUserAudiences`	Boolean	Whether to enable audience-based access for this publication.
`userAudienceMap`	Array	Array of audience assignments for this publication.
`userAudienceMap[].id`	String	ID of the audience to assign.
`userAudienceMap[].notifyNewBuildsProcessed`	Boolean	Whether users in this audience should be notified when a new build is processed.
`allowedCountries`	Array	ISO 3166-1 alpha-2 country codes to allow access from. Cannot be combined with `blockedCountries`.
`blockedCountries`	Array	ISO 3166-1 alpha-2 country codes to block access from. Cannot be combined with `allowedCountries`.

Build Selection Filter

Parameter	Type	Description
`filter.type`	String	Build selection strategy. Allowed values: `last`, `build`, `builds`, `gitBranch`, `gitTag`, `tag`.
`filter.value`	String	Required for `gitBranch`, `gitTag`, and `tag` filter types. The branch name, git tag, or build tag to match.
`filter.ios`	String	Build ID for the iOS build. Used when `filter.type` is `build`.
`filter.android`	String	Build ID for the Android build. Used when `filter.type` is `build`.
`filter.macos`	String	Build ID for the macOS build. Used when `filter.type` is `build`.
`filter.windows`	String	Build ID for the Windows build. Used when `filter.type` is `build`.
`filter.builds`	Array	Array of `{ buildPlatform, id }` objects. Used when `filter.type` is `builds`. Supports custom platforms: `ios`, `macos`, `android`, `ps4`, `ps5`, `switch`, `xbox-one`, `xbox-series`.

Build Display options

Parameter	Type	Description
`tags`	Array	Tags to categorize this publication.
`showHistory`	Boolean	Whether users can browse and install previous builds.
`showDevInfo`	Boolean	Whether to display technical build information (git metadata, certificate details, tags) to users.
`expirationDate`	String	ISO 8601 timestamp after which the publication becomes unavailable for download. Use to create time-limited distributions, beta programs, or promotional campaigns. E.g. `"2025-12-31T23:59:59Z"`. Set to `null` to remove an existing expiration date.

Legal Terms

Parameter	Type	Description
`terms.active`	Boolean	Whether users must accept legal terms before accessing the publication.
`terms.text`	String	The legal terms text to display. Required when `terms.active` is `true`.

Branding and App configuration overrides

Parameter	Type	Description
`configuration.application.name`	String	Overrides the app name displayed in the publication.
`configuration.application.description`	String	Overrides the app description displayed in the publication.
`configuration.branding.logo`	String	Overrides the store logo for this publication.
`configuration.branding.primaryColor`	String	Overrides the primary branding color (hex format). E.g. `#FF5733`.
`configuration.branding.buttonColor`	String	Overrides the button color (hex format).

Example Request

Update a publication to point to a specific git branch and restrict access to logged-in users in a specific group:

curl 'https://api.applivery.io/v1/integrations/distributions/552ae3cfcb5abfc58d733b81' \
  -X PUT \
  -H 'Authorization: Bearer YOUR_APP_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "slug": "my-app-staging",
    "security": "logged",
    "visibility": "active",
    "filter": {
      "type": "gitBranch",
      "value": "develop"
    },
    "groups": [["qa-team"]],
    "showHistory": true,
    "showDevInfo": true
  }'

Responses

{
  "status": true,
  "data": {
    "id": "string",
    "updatedAt": "string",
    "createdAt": "string",
    "application": "string",
    "applicationInfo": {
      "id": "string",
      "slug": "string",
      "name": "string",
      "picture": "string"
    },
    "slug": "string",
    "filter": {
      "type": "last",
      "value": "string",
      "ios": "string",
      "android": "string",
      "windows": "string",
      "macos": "string",
      "builds": [
        {
          "buildPlatform": "string",
          "id": "string"
        }
      ]
    },
    "security": "public",
    "tags": ["string"],
    "groups": [["string"]],
    "visibility": "active",
    "showHistory": true,
    "showDevInfo": true,
    "distributionUrl": "string",
    "terms": {
      "active": true,
      "text": "string"
    }
  }
}

Slug already in use.

{
  "status": false,
  "error": {
    "code": 5024,
    "message": "Slug already used"
  }
}

{
  "status": false,
  "error": {
    "code": 4002,
    "message": "No auth token"
  }
}

{
  "status": false,
  "error": {
    "code": 3001,
    "message": "Entity not found"
  }
}

Workspace API

Use this endpoint when updating publications at the workspace level using a single credential across multiple apps.

Authentication uses a Service Account token. To create a Service Account, see Service Accounts.

Endpoint

PUT https://api.applivery.io/v1/organizations/{organizationId}/stores/{storeId}/pubApps/{publishedApplicationId}

Path parameters

Parameter	Type	Required	Description
`organizationId`	String	Yes	The unique identifier of your Applivery organization.
`storeId`	String	Yes	The unique identifier of the store (app project).
`publishedApplicationId`	String	Yes	The unique identifier of the publication to update.

Authentication

Authorization: Bearer <your_service_account_token>

Example Request

curl 'https://api.applivery.io/v1/organizations/ORG_ID/stores/STORE_ID/pubApps/PUB_APP_ID' \
  -X PUT \
  -H 'Authorization: Bearer YOUR_SERVICE_ACCOUNT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "slug": "my-app-release",
    "security": "public",
    "visibility": "active",
    "filter": {
      "type": "last"
    }
  }'

The request body parameters and response schema are identical to the Integrations API.

Managing OTP Access users

OTP (One-Time Password) access is a Publication-level security option that allows you to share builds securely with external users — freelancers, QA studios, contractors — without requiring them to have an Applivery account or go through your SSO. This is particularly useful for organizations with strict SSO-only policies that need to share builds externally without relaxing their global authentication settings.

OTP access is configured per Publication and does not affect any other Publication or the global App Store authentication settings.

Note

OTP configuration can only be applied in edit mode — it must be set up after the publication has already been created. Enable it by setting security to "private" and enabling OTP in the dashboard, or by using the API endpoint described below to add users to the allowlist.

Note

OTP users are scoped to the specific Publication they accessed. They cannot browse or access other Publications in the App Store.

How it works

Admin side:

Create or update a publication with OTP access enabled (security: "private" + OTP allowlist configured).
Add the email addresses of authorized external users to the OTP allowlist, and configure each user's lifecycle and single-use settings.

User side:

The user visits the Publication URL and enters their email address.
If their email is on the allowlist, they receive a time-limited OTP via email (valid for 5–10 minutes).
They enter the code to verify their identity and gain access to download the app.
If single-use is enabled, their email is automatically removed from the allowlist after the first successful download.

Adding OTP Users via API

OTP users are managed separately from the publication configuration itself, via a dedicated endpoint. This endpoint is called after creating or updating a publication to add users to its OTP allowlist.

Endpoint

POST https://api.applivery.io/v1/organizations/{organizationSlug}/stores/{storeId}/otp-users

Authentication

Authorization: Bearer <your_service_account_token>

Path parameters

Parameter	Type	Required	Description
`organizationSlug`	String	Yes	The URL-friendly slug of your Applivery organization (not the numeric ID).
`storeId`	String	Yes	The unique identifier of the store the publication belongs to.

Body parameters

Parameter	Type	Required	Description
`email`	String	Yes	The email address of the external user to add to the OTP allowlist.
`temporal`	Boolean	No	Whether the user should be automatically removed after 30 days. Default: `true`. Set to `false` for persistent access.
`singleUse`	Boolean	No	Whether the user's access should be invalidated after the first successful download. Once downloaded, the email is removed from the allowlist and the user must be re-added to regain access. Default: `false`.

Example Request

curl 'https://api.applivery.io/v1/organizations/my-org-slug/stores/STORE_ID/otp-users' \
  -X POST \
  -H 'Authorization: Bearer YOUR_SERVICE_ACCOUNT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "[email protected]",
    "temporal": true,
    "singleUse": false
  }'

Responses

{
  "status": true,
  "data": {
    "id": "string",
    "email": "[email protected]",
    "temporal": true,
    "singleUse": false,
    "createdAt": "string"
  }
}

Email already exists in the OTP allowlist for this store.

Invalid or missing Service Account token.

Organization slug or store ID not found.

OTP configuration options reference

Option	Description
Allowlist	The list of email addresses authorized to request an OTP for this publication.
User lifecycle	`temporal: true` — OTP users are auto-deleted after 30 days. `temporal: false` — OTP users are retained indefinitely.
Single-use access	`singleUse: true` — the email is removed from the allowlist after the first successful download. The user cannot request another OTP unless re-added by an admin.
OTP expiry	OTPs are time-bound and single-use — valid for 5–10 minutes and cannot be reused even within the validity window.
New build notifications	When a new build is published, OTP users on the allowlist can receive a notification email with a fresh OTP, allowing them to download without requesting access again manually.

When to use OTP Access

Scenario	Recommended approach
Share a build with an external freelancer for a one-time review	OTP + `singleUse: true`
Share a beta with an external QA studio for a limited test period	OTP + Expiring Publication
Distribute to a list of external testers without permanent accounts	OTP + `temporal: true` (30-day auto-cleanup)
Long-term external collaborators needing ongoing access	Private Publication + Audience-based access instead of OTP

Tip

For maximum control over time-limited external access, combine OTP with an Expiring Publication. This ensures access is both identity-verified (via OTP allowlist) and time-bounded (via Publication expiry) — with no manual cleanup needed once the deadline passes.

PUT - Update a Publication

Choosing the right API

Integrations API

Endpoint

Authentication

Request format

Path parameters

Parameters

Identity and Visibility

Security and Access Control

Build Selection Filter

Build Display options

Legal Terms

Branding and App configuration overrides

Example Request

Responses

Workspace API

Endpoint

Path parameters

Authentication

Example Request

Managing OTP Access users

How it works

Adding OTP Users via API

Endpoint

Authentication

Path parameters

Body parameters

Example Request

Responses

OTP configuration options reference

When to use OTP Access

Key Takeaways