# Mobile provider

Workspace Limrun keys for mobile emulators and devices.

See the [OpenAPI document](/openapi.json) for schemas and operation IDs.

## Prerequisites

- Protected operations require an API key in `x-api-key` or a browser session cookie; some actions require a verified user session
- Tenant-scoped operations use `X-Organization-Id`; browser sessions can use their active workspace. Discovery and personal-workspace bootstrap do not require an active workspace
- The base URL for your deployment, `https://server.hlix.ai` by default

## Operations

| Method | Path | Operation |
| --- | --- | --- |
| `GET` | `/v1/api/mobile-provider` | [Read mobile emulators and devices billing configuration](#read-mobile-emulators-and-devices-billing-configuration) |
| `PATCH` | `/v1/api/mobile-provider` | [Choose workspace or Hlix funding for new mobile builds](#choose-workspace-or-hlix-funding-for-new-mobile-builds) |
| `DELETE` | `/v1/api/mobile-provider/key` | [Remove the key for new builds; existing resources retain their cleanup credentials](#remove-the-key-for-new-builds-existing-resources-retain-their-cleanup-credentials) |
| `PUT` | `/v1/api/mobile-provider/key` | [Verify and save a workspace Limrun key for new builds](#verify-and-save-a-workspace-limrun-key-for-new-builds) |
| `POST` | `/v1/api/mobile-provider/test` | [Check a supplied or saved Limrun key without allocating a device](#check-a-supplied-or-saved-limrun-key-without-allocating-a-device) |

## Read mobile emulators and devices billing configuration

`GET /v1/api/mobile-provider` · operation ID `getMobileProvider`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | MobileProviderState | Workspace mobile-provider state; no credentials are returned. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Agency-only reads; owner or admin required for credential changes and tests. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |
| `503` | ApiError | Settings are temporarily unavailable. |

## Choose workspace or Hlix funding for new mobile builds

`PATCH /v1/api/mobile-provider` · operation ID `toggleMobileProvider`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Request body** — `application/json`, `ToggleMobileProvider` (required)

| Property | Type | Required | Notes |
| --- | --- | --- | --- |
| `enabled` | boolean | **yes** |  |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | MobileProviderState | Workspace mobile-provider state; no credentials are returned. |
| `400` | ValidationError \| ApiError | The JSON body failed schema validation (`ValidationError`), or the request named no active organization (`ApiError`). |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Agency-only reads; owner or admin required for credential changes and tests. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |
| `409` | ApiError | Save a key before enabling it. |
| `503` | ApiError | Settings are temporarily unavailable. |

## Remove the key for new builds; existing resources retain their cleanup credentials

`DELETE /v1/api/mobile-provider/key` · operation ID `removeMobileProviderKey`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | MobileProviderState | Workspace mobile-provider state; no credentials are returned. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Agency-only reads; owner or admin required for credential changes and tests. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |
| `503` | ApiError | Settings are temporarily unavailable. |

## Verify and save a workspace Limrun key for new builds

`PUT /v1/api/mobile-provider/key` · operation ID `saveMobileProviderKey`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Request body** — `application/json`, `SaveMobileProviderKey` (required)

| Property | Type | Required | Notes |
| --- | --- | --- | --- |
| `apiKey` | string | **yes** | min length 8, max length 4096 |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | MobileProviderState | Workspace mobile-provider state; no credentials are returned. |
| `400` | ValidationError \| ApiError | The JSON body failed schema validation (`ValidationError`), or the request named no active organization (`ApiError`). |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Agency-only reads; owner or admin required for credential changes and tests. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |
| `502` | ApiError | Limrun could not verify the key; no key material is returned. |
| `503` | ApiError | Settings are temporarily unavailable. |

## Check a supplied or saved Limrun key without allocating a device

`POST /v1/api/mobile-provider/test` · operation ID `testMobileProviderKey`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Request body** — `application/json`, `TestMobileProviderKey` (required)

| Property | Type | Required | Notes |
| --- | --- | --- | --- |
| `apiKey` | string | no | min length 8, max length 4096 |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | MobileProviderTest | The account can be read with this key; no billable instance was started. |
| `400` | ValidationError \| ApiError | The JSON body failed schema validation (`ValidationError`), or the request named no active organization (`ApiError`). |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Agency-only reads; owner or admin required for credential changes and tests. |
| `404` | ApiError | No key has been saved. |
| `502` | ApiError | Limrun could not verify the key; no key material is returned. |
| `503` | ApiError | Settings are temporarily unavailable. |

## If a request fails

The response table for each operation lists its documented errors. Common status codes include:

- `400` — the body failed schema validation, or the request named no active organization. A `ValidationError` body carries the failing fields; an `ApiError` body carries only `error`.
- `401` — no valid session or API key.
- `403` — authenticated, but not a member of the named organization, or a client collaborator without the required access.
- `404` — check the resource ID and your access to the selected Workspace.
- `409` — the expected revision or state is stale, or another operation currently owns the transition.
- `500` — the operation failed server-side. Retry only where an idempotency key makes that safe.

## Next steps

[API reference](/api/reference/)
  [API & OpenAPI](/api/openapi/)
  [TypeScript SDK](/sdk/typescript/)
  [CLI reference](/reference/cli/)