# Download Token & URL

> Programmatically download Builds from Applivery via the API. Generate download tokens and resolve download URLs for .apk, .ipa, and .aab files.

Source: https://docs.applivery.com/en/app-distribution/api/builds/download-token-url-build/  •  Last updated: 2026-04-22

**Key topics:** Download Token Generation, Download URL Resolution, Service Account Authentication, API Endpoints, Error Handling, Applivery, API, Service Account, apk, ipa, aab, curl, JSON

---

**TL;DR:** Download Applivery builds programmatically by generating a short-lived download token with a Service Account and then resolving the download URL.

Downloading a Build programmatically requires a **two-step process**: first, generate a short-lived download token, then use that token to resolve the actual download URL. The download URL is served via a redirect response.

:::warning
Unlike the other build endpoints, the download token endpoint is **only available through the Workspace API** and requires a **Service Account token** or a user session token obtained at login. The Integrations API (App API Token) does not support this endpoint.
:::

To create a Service Account, see [Service Accounts](https://docs.applivery.com/en/platform/api/service-accounts/).

* * *

## Overview: Download flow

```
Step 1: Generate a download token
  GET /v1/organizations/{organizationId}/apps/{applicationId}/builds/{buildId}/downloadToken
  → returns { token, expiresAt }

Step 2: Resolve the download URL
  GET https://download-api.applivery.io/v1/download/{token}
  → HTTP 302 redirect to the actual file URL
```

* * *

**Generate a Download Token**

Generates a short-lived, single-use token that authorizes the download of a specific Build file.

**Endpoint**

```
GET https://api.applivery.io/v1/organizations/{organizationId}/apps/{applicationId}/builds/{buildId}/downloadToken
```

**Authentication**

```
Authorization: Bearer <your_service_account_token>
```

**Path parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `organizationId` | String | Yes | The unique identifier (or slug) of your Applivery organization. |
| `applicationId` | String | Yes | The unique identifier of the App the Build belongs to. |
| `buildId` | String | Yes | The unique identifier of the Build you want to download. Returned by POST – Upload a Build and GET – List of Builds. |

**Query parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | String | Yes | Specifies which file format to generate the download token for. See values below. |

`type` **values**

| Value | Description |
| --- | --- |
| `auto` | Default behavior. Returns a `.apk` for Android Builds, or the manifest (`.plist`) for Apple Builds. This is the standard option for in-app installation flows. |
| `file` | Returns the raw binary file. For Apple Builds, this is the `.ipa` or `.pkg` file instead of the manifest. Use this when you need the actual file rather than an OTA install link. |
| `aab` | For Android Builds originally uploaded as an `.aab`, this returns the original `.aab` file instead of the Universal `.apk` that Applivery generates from it. |

**Example Request**

```bash
curl 'https://api.applivery.io/v1/organizations/MY_ORG_SLUG/apps/MY_APP_ID/builds/MY_BUILD_ID/downloadToken?type=file' \
  -X GET \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_SERVICE_ACCOUNT_TOKEN'
```

**Responses**

**✓ 200 OK**

```json
{
  "status": true,
  "data": {
    "token": "string",
    "expiresAt": "string"
  }
}
```

**✗ 400 Bad Request**

Build not yet processed. The Build exists but has not finished processing. Only Builds with `status: processed` can have download tokens generated.

```json
{
  "status": false,
  "error": {
    "code": 5014,
    "message": "Build Not Processed"
  }
}
```

**✗ 401 Unauthorized**

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

**✗ 404 Not Found**

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

| Field | Description |
| --- | --- |
| `token` | The download token string. Pass this as the path parameter to Step 2 to resolve the download URL. |
| `expiresAt` | ISO 8601 timestamp indicating when the token expires. Tokens are short-lived — use them promptly after generation. |

**Resolve the Download URL**

Uses the token obtained in Step 1 to get the actual file download URL. The API responds with an HTTP `302 Found` redirect to the file's storage location.

:::warning
**No authentication required**. This endpoint is public — the token itself acts as the credential. Anyone with the token can download the file, so treat tokens as sensitive and do not share them beyond the intended recipient.
:::

**Endpoint**

```
GET https://download-api.applivery.io/v1/download/{token}
```

**Path parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | String | Yes | The download token returned in Step 1. |

**Example Request**

```bash
curl -L 'https://download-api.applivery.io/v1/download/YOUR_DOWNLOAD_TOKEN' \
  -o downloaded_build.ipa
```

:::info
The `-L` flag instructs curl to follow the `302` redirect automatically. Without it, you will receive the redirect response with the `Location` header containing the actual file URL, but no file will be downloaded.
:::

**Redirect behavior by platform**

The URL in the `Location` redirect header varies depending on the platform and the `type` parameter used in Step 1:

| Platform | `type` value | Redirect target |
| --- | --- | --- |
| **Android** | `auto` | Universal `.apk` file |
| **Android** | `aab` | Original `.aab` file |
| **Apple** | `auto` | OTA manifest (`.plist`) — for in-app installation via MDM or direct install link |
| **Apple** | `file` | Raw binary — `.ipa` for iOS, `.pkg` for macOS |

**Responses**

**✓ 302 Found**

Redirect to the file URL.  
The response does not have a body. The actual download URL is in the `Location` response header. Follow the redirect to download the file.

**✗ 401 Unauthorized**

Token expired. Download tokens are short-lived. If the token has expired, generate a new one from Step 1.

```json
{
  "status": false,
  "error": {
    "code": 4005,
    "message": "Token Expired"
  }
}
```

**✗ 404 Not Found**

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

* * *

## Complete example: Download a Build file

```bash
# Step 1: Generate the download token
TOKEN=$(curl -s \
  'https://api.applivery.io/v1/organizations/MY_ORG/apps/MY_APP/builds/MY_BUILD/downloadToken?type=file' \
  -H 'Authorization: Bearer YOUR_SERVICE_ACCOUNT_TOKEN' \
  | jq -r '.data.token')

# Step 2: Download the file, following the redirect
curl -L \
  "https://download-api.applivery.io/v1/download/$TOKEN" \
  -o my_build.ipa
```