Esper tenant_VPP Token Management API

openapi: 3.2.0
info:
  title: ESPER API REFERENCE tenant_VPP Token Management API
  x-logo:
    url: esper-logo-white.svg
    backgroundColor: '#141418'
    altText: Logo
  description: '# Introduction

    Welcome to Esper’s API documentation. The Esper API allows users to accomplish operations outside of the console. Some common uses for our APIs include observing device information and console activity, installing and updating apps, uploading files, and sending files to devices. Our users have also used the API to automate app updates, perform bulk actions, and more. Esper API endpoints use REST-based architecture and return JSON responses. See our documentation for:


    * Getting started guides

    * Commonly used API examples

    * API command examples

    * Automated Script examples

    * And more


    # Authentication


    You need to create an API Key to interact with our APIs. Learn more about generating an API Key. You can also learn more about Esper and sign up for an account at esper.io/signup. Some endpoints also require an Enterprise ID. This ID can be found in the API Management section of the Esper console. # Lifecycle Labels


    Esper uses lifecycle labels to communicate the support status of each API endpoint. Use the following table to understand what each label means and how to respond. Badge

    What it means

    Recommended action


    Stable

    This endpoint is fully supported and safe for production use. No action needed. Beta

    This endpoint is publicly available but may change. It is not recommended for production integrations. Use with caution. Monitor the API changelog for updates before relying on this endpoint. Legacy

    This endpoint uses an older architecture and is still supported, but a newer equivalent exists. It is not recommended for new integrations. Plan migration to the recommended replacement when possible. See the endpoint description for the alternative. Deprecated

    This endpoint has stopped being supported. A removal date may be added at a later time. A replacement is available or the feature is entirely retired. Migrate before the removal date listed in the endpoint description. Do not use this endpoint in new integrations. # Pagination


    Responses may be paginated. Use the following parameters to query the data. A full list of parameters can be found on the endpoint’s documentation page. Parameter

    Data Type

    Explanation


    limit

    integer

    Limit the data returned. Default = 20. offset

    integer

    Offset to the first item returned. Default = 0. ordering

    string

    Order the results set by the field name. Varies by endpoint. next

    string

    Paginate to the next response set. previous

    string

    Paginate to the last set response. # Errors

    We use standard HTTP status codes for success or failure. A typical error response may look something like this:


    ```json

    {

    "errors": [],

    "message": "error message",

    "status": 400

    }

    ```

    * `errors` - List of error details

    * `message` - Error description

    * `status` - HTTP status code


    Some common status codes and messages are:


    Number

    Message

    Explanation


    200

    OK

    The request succeeded. 201

    Resource creation

    A resource was created. 401

    Unauthorized

    The API key is invalid. 404

    Not found

    The resource was not found. 429

    Rate limit exceeded

    Too many requests. Wait a moment and try again. 500

    Server error

    Internal error. Wait a moment and try again. If the issue persists, contact Esper. See how our systems are doing by checking our status page. # Rate Limits

    To ensure quality of service for all customers, we enforce rate limits for API requests. Most customers won’t hit this limit with normal use. In case you experience 429 or rate limit exceeded errors, we recommend the following:

    * Try sending requests in batches. * Begin with about 20 requests at a time and building up from there. * Ensure your scripts are efficient and don’t contain redundant calls. * Reach out to your account manager to discuss your options.'
  termsOfService: https://esper.io/terms-of-service
  contact:
    email: developer@esper.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
  x-prefix-tag: esper cloud api
servers:
- url: https://{foo}-api.esper.cloud/api
  variables:
    foo:
      default: develop
      description: Custom end point
tags:
- name: tenant_VPP Token Management
  description: APIs to create, access, and delete VPP tokens. Learn more about VPP tokens.
  x-displayName: VPP Token Management
paths:
  /tenant/v0/vpptokens/:
    get:
      x-badges:
      - name: Stable
        color: green
      security:
      - tenant_apiKey: []
      summary: Get all VPP tokens for the tenant
      description: '⚠️ iOS/iPadOS/tvOS only.


        Returns all Volume Purchase Program (VPP) tokens registered to the Esper tenant.


        Use this endpoint to audit which VPP tokens are currently on file, check their metadata and expiry status, and identify tokens that need renewal before they affect app distribution.


        **About List VPP Tokens**


        VPP tokens enable Esper to distribute paid and free apps from the Apple App Store to managed iOS devices on behalf of an Apple Business organization. Each token is associated with a specific location in Apple Business, and Esper recommends tying one token to one location to avoid app installation conflicts. Tokens expire annually and must be renewed before expiry to maintain uninterrupted app management. The response includes pagination fields (count, next, previous) and an array of VPPToken objects.


        **Key Fields / Query Parameters**


        id — UUID of the VPP token record in Esper.


        meta — Object containing token metadata, including expiry information.


        created_at / updated_at — Timestamps for auditing when the token was uploaded or last modified.


        **Common Use Cases**


        Retrieving all VPP tokens to check expiry dates before the annual renewal window


        Auditing which Apple Business locations have active tokens registered in Esper


        Verifying a VPP token was successfully stored after upload


        **Best Practices**


        Monitor meta for expiry dates and renew tokens before they lapse; expired VPP tokens will block app installations and updates on enrolled iOS devices.


        Associate each VPP token with a dedicated, Esper-specific Apple Business location to prevent conflicts with other MDM platforms.


        If you manage multiple regions, use the VPP country selection feature in Apple MDM Management to configure up to five countries per token.'
      tags:
      - tenant_VPP Token Management
      responses:
        '200':
          description: VPP tokens for the Tenant
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    default: 200
                  message:
                    type: string
                  content:
                    type: object
                    properties:
                      count:
                        type: integer
                      previous:
                        type: string
                      next:
                        type: string
                      results:
                        type: array
                        items:
                          $ref: '#/components/schemas/tenant_VPPToken'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tenant_Error_401_Unauthorized'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tenant_Error_500_Internal_Server_Error'
      operationId: getTenantV0Vpptokens
      x-operation-id-source: derived
    post:
      x-badges:
      - name: Stable
        color: green
      security:
      - tenant_apiKey: []
      summary: Store a VPP token
      description: '⚠️ iOS/iPadOS/tvOS only.


        Uploads a VPP token file to the Esper tenant to enable Apple App Store app distribution on managed iOS devices.


        Submit the token as multipart/form-data; on success, Esper stores the token and returns the new VPPToken record with its assigned id for use in subsequent operations.


        **About Upload VPP Token**


        A VPP (Volume Purchase Program) token is a .vpptoken file downloaded from an Apple Business location''s Apps & Books settings. Uploading it to Esper grants the tenant the ability to assign and install App Store apps on enrolled iOS devices without requiring individual Apple IDs on each device. Esper recommends creating a dedicated Apple Business location specifically for your Esper MDM integration before downloading and uploading the token. If migrating from another MDM platform, the existing VPP token should be migrated to avoid losing app licenses.


        **Key Fields / Query Parameters**


        filename (form field, binary) — The .vpptoken file downloaded from Apple Business.


        **Common Use Cases**


        Initial setup of iOS app management after configuring Apple MDM Management in Esper


        Migrating a VPP token from a previous MDM platform to Esper


        Adding a second VPP token for a new Apple Business location or region


        **Best Practices**


        Create and use a dedicated Apple Business location for Esper before downloading the VPP token to avoid conflicts with other MDM platforms sharing the same token.


        Download the token from the correct MDM server entry in Apple Business (it will match the location name).


        After upload, verify the token was stored correctly via GET /api/tenant/v0/vpptokens/ before assigning apps to devices.


        **Workflow**


        In Apple Business, create a location dedicated to Esper MDM and navigate to Settings > Payments & Billing > Apps & Books.


        Select the linked Esper MDM server and download the .vpptoken file.


        POST the file as multipart/form-data to /api/tenant/v0/vpptokens/.


        Confirm the returned VPPToken record and note the id for future reference.'
      tags:
      - tenant_VPP Token Management
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                filename:
                  type: string
                  format: binary
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    default: 201
                  message:
                    type: string
                  content:
                    $ref: '#/components/schemas/tenant_VPPToken'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tenant_Error_400_Bad_Data'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tenant_Error_401_Unauthorized'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tenant_Error_500_Internal_Server_Error'
      operationId: postTenantV0Vpptokens
      x-operation-id-source: derived
  /tenant/v0/vpptokens/{id}:
    delete:
      x-badges:
      - name: Stable
        color: green
      security:
      - tenant_apiKey: []
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        required: true
      summary: Delete VPP Token
      description: '⚠️ iOS/iPadOS/tvOS only.


        Deletes a VPP token from the Esper tenant by its ID.


        Once deleted, Esper can no longer distribute or manage Apple App Store apps associated with that token''s Apple Business location; previously installed apps remain on devices but cannot be updated or reassigned through Esper.


        **About Delete VPP Token**


        VPP tokens link Esper to a specific Apple Business location for app license management. Removing a token from Esper does not revoke app licenses in Apple Business, but it ends Esper''s ability to manage those licenses going forward. This action is appropriate when retiring an Apple Business location, replacing a token with a renewed one, or decommissioning iOS app management entirely. Use the id returned from GET /api/tenant/v0/vpptokens/ or POST /api/tenant/v0/vpptokens/ to identify the correct token.


        **Key Fields / Query Parameters**


        id (path, required, integer) — The identifier of the VPP token record to delete.


        **Common Use Cases**


        Removing an expired token before uploading a renewed one


        Cleaning up a stale token from a retired Apple Business location


        Decommissioning iOS app management for the tenant


        **Best Practices**


        Before deleting, verify that no active iOS devices are relying on app licenses managed through this token.


        Upload a replacement token via POST /api/tenant/v0/vpptokens/ immediately after deletion to minimize disruption to app management.


        Confirm the correct token using GET /api/tenant/v0/vpptokens/ before deleting, especially in tenants with multiple VPP tokens.'
      tags:
      - tenant_VPP Token Management
      responses:
        '204':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: response code
                    default: 204
                  message:
                    type: string
                    description: response message
                  content:
                    type: object
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tenant_Error_401_Unauthorized'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tenant_Error_404_Not_Found'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tenant_Error_500_Internal_Server_Error'
      operationId: deleteTenantV0VpptokensById
      x-operation-id-source: derived
components:
  schemas:
    tenant_Error_401_Unauthorized:
      type: object
      properties:
        code:
          type: integer
          format: int32
          default: 401
        message:
          type: string
        content:
          type: object
      required:
      - code
      - message
    tenant_VPPToken:
      type: object
      properties:
        id:
          type: string
          format: uuid
        tenant_id:
          type: string
          maxLength: 64
        key:
          type: string
          maxLength: 256
        meta:
          type: object
        created_by:
          type: string
          maxLength: 64
        updated_by:
          type: string
          maxLength: 64
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - tenant_id
      - created_by
      - updated_by
    tenant_Error_404_Not_Found:
      type: object
      properties:
        code:
          type: integer
          format: int32
          default: 404
        message:
          type: string
        content:
          type: object
      required:
      - code
      - message
    tenant_Error_500_Internal_Server_Error:
      type: object
      properties:
        code:
          type: integer
          format: int32
          default: 500
        message:
          type: string
        content:
          type: object
      required:
      - code
      - message
    tenant_Error_400_Bad_Data:
      type: object
      properties:
        code:
          type: integer
          format: int32
          default: 400
        message:
          type: string
        content:
          type: object
      required:
      - code
      - message
  securitySchemes:
    esper_cloud_api_apiKey:
      type: http
      scheme: bearer
      description: "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper Console at `<domain>-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n    curl -X GET \\\n      https://<domain>-api.esper.cloud/api/enterprise/<enterprise_id>/device/ \\\n      -H 'Authorization: Bearer <ACCESS_TOKEN>' \\\n      -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n"
    pipelines_SCAPIAuthToken:
      type: http
      scheme: bearer
    device_apiKey:
      type: http
      scheme: bearer
      description: "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper Console at `<domain>-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n    curl -X GET \\\n      https://<domain>-api.esper.cloud/api/enterprise/<enterprise_id>/device/ \\\n      -H 'Authorization: Bearer <ACCESS_TOKEN>' \\\n      -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n"
    apps_management_apiKey:
      type: http
      scheme: bearer
      description: "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper Console at `<domain>-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n    curl -X GET \\\n      https://<domain>-api.esper.cloud/api/enterprise/<enterprise_id>/device/ \\\n      -H 'Authorization: Bearer <ACCESS_TOKEN>' \\\n      -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n"
    commands_apiKey:
      type: http
      scheme: bearer
      description: "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper Console at `<domain>-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n    curl -X GET \\\n      https://<domain>-api.esper.cloud/api/enterprise/<enterprise_id>/device/ \\\n      -H 'Authorization: Bearer <ACCESS_TOKEN>' \\\n      -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n"
    drift_apiKey:
      type: http
      scheme: bearer
      description: "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper Console at `<domain>-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n    curl -X GET \\\n      https://<domain>-api.esper.cloud/api/enterprise/<enterprise_id>/device/ \\\n      -H 'Authorization: Bearer <ACCESS_TOKEN>' \\\n      -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n"
    device_onboarding_apiKey:
      type: http
      scheme: bearer
      description: "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper Console at `<domain>-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n    curl -X GET \\\n      https://<domain>-api.esper.cloud/api/enterprise/<enterprise_id>/device/ \\\n      -H 'Authorization: Bearer <ACCESS_TOKEN>' \\\n      -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n"
    tenant_apiKey:
      type: http
      scheme: bearer
      description: "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper Console at `<domain>-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n    curl -X GET \\\n      https://<domain>-api.esper.cloud/api/enterprise/<enterprise_id>/device/ \\\n      -H 'Authorization: Bearer <ACCESS_TOKEN>' \\\n      -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n"
    foundation_AuthToken:
      type: apiKey
      in: header
      name: Authorization
    reports_bearerAuth:
      type: http
      scheme: bearer
    geofence_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-tagGroups:
- name: ESPER CLOUD API
  tags:
  - esper_cloud_api_Company Settings
  - esper_cloud_api_Application
  - esper_cloud_api_Application V1
  - esper_cloud_api_AndroidDevice
  - esper_cloud_api_Device Group
  - esper_cloud_api_Token (Deprecated)
  - esper_cloud_api_Commands V2
  - esper_cloud_api_Enterprise Policy
  - esper_cloud_api_Geofence
  - esper_cloud_api_Content
  - esper_cloud_api_User (Deprecated)
  - esper_cloud_api_User
  - esper_cloud_api_Blueprint (Deprecated)
  - esper_cloud_api_Directory Record
  - esper_cloud_api_Tile Icon
  - esper_cloud_api_Alerts
  - esper_cloud_api_Alarms
  - esper_cloud_api_Wallpapers
  - esper_cloud_api_Device Telemetry
  - esper_cloud_api_Daily and Custom Reports
  - esper_cloud_api_SSO Connections
  - esper_cloud_api_Roles
  - esper_cloud_api_Personal Access Token
- name: BLUEPRINTS
  tags:
  - blueprints_Blueprints API
  - blueprints_Custom Actions API
  - blueprints_Background Scripts API
- name: PIPELINES
  tags:
  - pipelines_System Status Code
  - pipelines_System
  - pipelines_Pipelines
  - pipelines_Stages
  - pipelines_Target Lists
  - pipelines_Targets
  - pipelines_Device Groups
  - pipelines_Operation Lists
  - pipelines_Operations
  - pipelines_Pipeline Runs
  - pipelines_Stage Runs
  - pipelines_Target Runs
- name: DEVICE
  tags:
  - device_Device
  - device_Device Heartbeat
  - device_Device Apps
  - device_Device Enrollment in EMM
  - device_Operations
  - device_DeviceOperations
  - device_MultiOS Remote Viewer
- name: APPS MANAGEMENT
  tags:
  - apps_management_VPP License Management
  - apps_management_VPP App Management
  - apps_management_Tenant Apps
  - apps_management_Apple App Store
  - apps_management_App List
  - apps_management_Webclips
  - apps_management_Provisioning Profiles
  - apps_management_Preferred Regions
  - apps_management_OEM Config Schema
  - apps_management_Esper Apps
  - apps_management_Tenant Esper Apps
- name: COMMANDS
  tags:
  - commands_Command Request
  - commands_Command Status
- name: DRIFT
  tags:
  - drift_Converge
  - drift_Converge Command
  - drift_Blueprint Drift
- name: DEVICE ONBOARDING
  tags:
  - device_onboarding_DEP Sync Request
  - device_onboarding_ABM Provisioning
- name: TENANT
  tags:
  - tenant_APNs certificate
  - tenant_DEP Profile
  - tenant_DEP Tokens
  - tenant_VPP Token Management
  - tenant_Google Enterprise
  - tenant_MDM Service Config
- name: FOUNDATION
  tags:
  - foundation_FoundryBuilds
  - foundation_FoundryDeviceModels
  - foundation_FoundryEvents
- name: REPORTS
  tags:
  - reports_Reports API
- name: GEOFENCE
  tags:
  - geofence_Geofences
  - geofence_Device State
x-provenance:
  method: harvested
  publisher: Esper
  source: https://api.esper.io/_bundle/openapi.json?download
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)