Create a cross-workspace app transfer

POST

/v1/app-transfers

curl --request POST \
  --url https://api.aetherpush.com/v1/app-transfers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "appName": "MyApp", "email": "new-owner@example.com" }'

• Production

Creates a pending transfer of an app the caller owns to an account in another workspace. The destination account must accept via POST /v1/app-transfers/{transferId}/accept. Requires the apps scope and app.transfer on the app. Same-workspace ownership moves use POST /v1/apps/{appName}/transfers instead.

Authorizations

• accessKeyAuth
• apiKeyAuth
  apps

Request Body^required

Media typeapplication/json

object

appName

required

Name of the app to transfer, as known to the calling account.

string

email

required

Email of the destination account in another workspace.

string format: email

Example

{
  "appName": "MyApp",
  "email": "new-owner@example.com"
}

Responses

201

Pending transfer created.

Media typeapplication/json

object

transfer

required

object

id

required

string format: uuid

appId

required

string

appName

Present on list responses; may be omitted on create.

string

fromAccountId

required

string

toAccountId

required

string

fromTenantId

required

string format: uuid

toTenantId

required

string format: uuid

fromEmail

Present on list responses; may be omitted on create.

string format: email

toEmail

Present on list responses; may be omitted on create.

string format: email

status

required

string

Allowed values: pending accepted cancelled expired

createdAt

required

string format: date-time

expiresAt

required

string format: date-time

warnings

required

object

quotaExceeded

required

True when accepting would push the destination tenant over its app quota. The transfer is still created; accept will fail until quota allows it.

boolean

nameConflict

required

True when the destination tenant already has an app with the same name. The transfer is still created; accept will fail until the name clash is resolved.

boolean

Example

{
  "transfer": {
    "status": "pending"
  }
}

400

Missing or invalid appName or email, or the target account is not a valid cross-workspace destination.

Media typeapplication/json

Error

Standard error envelope. code is the stable machine identifier for client branching and i18n. The wording of error is a human-readable fallback and is not part of the contract. Specialized responses keep narrower code enums where clients already branch on them.

object

error

required

Human-readable error message.

string

code

required

Stable machine code. Prefer this over matching on error. The values this API can answer with are listed in the ApiErrorCode schema of the raw document at https://api.aetherpush.com/openapi.yaml. The field stays an open string here so that a release adding a value does not invalidate this response.

string

requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string

Example

{
  "error": "The requested resource was not found.",
  "code": "not_found",
  "requestId": "req_abc123"
}

401

Unauthenticated.

Media typeapplication/json

Error

Standard error envelope. code is the stable machine identifier for client branching and i18n. The wording of error is a human-readable fallback and is not part of the contract. Specialized responses keep narrower code enums where clients already branch on them.

object

error

required

Human-readable error message.

string

code

required

Stable machine code. Prefer this over matching on error. The values this API can answer with are listed in the ApiErrorCode schema of the raw document at https://api.aetherpush.com/openapi.yaml. The field stays an open string here so that a release adding a value does not invalidate this response.

string

requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string

Example

{
  "error": "The requested resource was not found.",
  "code": "not_found",
  "requestId": "req_abc123"
}

403

The API key’s scopes do not grant apps, which answers required_scopes; or the caller’s role on the app does not grant app.transfer, which answers a plain error. Access keys and login sessions hold wildcard scope, so they never receive the scope refusal. Other refusals raised before the route, such as a request that did not arrive through the trusted edge, also answer a plain error.

Media typeapplication/json

One of:

Error

Error

Standard error envelope. code is the stable machine identifier for client branching and i18n. The wording of error is a human-readable fallback and is not part of the contract. Specialized responses keep narrower code enums where clients already branch on them.

object

error

required

Human-readable error message.

string

code

required

Stable machine code. Prefer this over matching on error. The values this API can answer with are listed in the ApiErrorCode schema of the raw document at https://api.aetherpush.com/openapi.yaml. The field stays an open string here so that a release adding a value does not invalidate this response.

string

requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string

InsufficientScopesError

InsufficientScopesError

Returned when an API key’s scopes do not grant the scope a management route requires. required_scopes lists what the route asked for, not what the key holds. Access keys and login sessions carry wildcard scope and pass the check without reaching this response, so only apiKeyAuth callers receive it. A key whose only scope is keys gets this on every management route, because that scope grants nothing, which is also why keys never appears in required_scopes.

object

error

required

string

code

required

string

Allowed values: insufficient_scopes

required_scopes

required

The scopes the route requires. Only these three appear: no management route requires keys.

Array<string>

Allowed values: read deploy apps

requestId

string

Examples

The API key's scopes do not grant apps

{
  "error": "Insufficient permissions",
  "code": "insufficient_scopes",
  "required_scopes": [
    "apps"
  ],
  "requestId": "req_abc123"
}

The caller's role does not grant app.transfer

{
  "error": "This action requires the app.transfer permission on the app!",
  "code": "forbidden",
  "requestId": "req_abc123"
}

404

App not found.

Media typeapplication/json

Error

Standard error envelope. code is the stable machine identifier for client branching and i18n. The wording of error is a human-readable fallback and is not part of the contract. Specialized responses keep narrower code enums where clients already branch on them.

object

error

required

Human-readable error message.

string

code

required

Stable machine code. Prefer this over matching on error. The values this API can answer with are listed in the ApiErrorCode schema of the raw document at https://api.aetherpush.com/openapi.yaml. The field stays an open string here so that a release adding a value does not invalidate this response.

string

requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string

Example

{
  "error": "The requested resource was not found.",
  "code": "not_found",
  "requestId": "req_abc123"
}

409

A pending outbound transfer for this app already exists.

Media typeapplication/json

Error

Standard error envelope. code is the stable machine identifier for client branching and i18n. The wording of error is a human-readable fallback and is not part of the contract. Specialized responses keep narrower code enums where clients already branch on them.

object

error

required

Human-readable error message.

string

code

required

Stable machine code. Prefer this over matching on error. The values this API can answer with are listed in the ApiErrorCode schema of the raw document at https://api.aetherpush.com/openapi.yaml. The field stays an open string here so that a release adding a value does not invalidate this response.

string

requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string

Example

{
  "error": "The requested resource was not found.",
  "code": "not_found",
  "requestId": "req_abc123"
}

429

The tenant’s per-minute management API budget is spent. Retry-After and X-RateLimit-* say when to retry. This is not a plan quota: quota 429s use the Error envelope and do not set Retry-After.

Media typeapplication/json

RateLimitError

Returned with HTTP 429 when an endpoint-specific rate limit is hit, including the per-tenant management API budget. Not the process-wide address limiter (see GlobalAddressRateLimitErrorResponse). retryAfterSeconds indicates how long the client should wait before retrying, and matches the Retry-After header when that header is set. code names the limit that fired so clients can translate without matching on error.

object

error

required

string

code

required

string

retryAfterSeconds

required

integer

>= 1

requestId

string

Example

{
  "error": "Rate limit exceeded",
  "code": "tenant_rate_limit_exceeded",
  "retryAfterSeconds": 60
}

Headers

Retry-After

integer

>= 1

Seconds until the tenant window resets.