Apps

Apps represent the server-side integrations that call Commerce APIs. Create an app when you need a new API identity for a service, environment, tenant, or backend integration.

The app object

An app object contains the human-readable metadata and stable identifier for a Commerce API identity. Secret key values are not returned on normal app lookups; the initial token appears only in the response from Create an app.

Properties

Name
alias
Type
string
Description
Optional short label for the app. Use this for names that are easier to scan in dashboards, logs, or internal tooling than the generated app ID.
Name
archived_at
Type
timestamp
Description
When the app was archived. Null while the app is active.
Name
created_at
Type
timestamp
Description
When the app was created.
Name
description
Type
string
Description
Optional longer description of what the app is used for.
Name
id
Type
string
Description
Unique identifier for the app. App IDs begin with the app_ prefix.
Name
name
Type
string
Description
Display name for the app.
Name
updated_at
Type
timestamp
Description
When the app metadata was last updated. Null if the app has not been updated.

Create an app

Create a Commerce app and its first secret key. Use this endpoint when provisioning a new backend service, environment, or integration that needs its own API identity.

Store app.secret_key.token immediately after the response is received. The full token is returned only at creation time and is not included in later lookup or update responses.

Request attributes

Name
alias
Type
string
Description
Optional short label for the app. The API trims surrounding whitespace before storing it.
Name
description
Type
string
Description
Optional description of what the app is used for.
Name
legal_entity_type
Type
string
Description
Optional legal-entity classification. The API trims surrounding whitespace and stores the supplied string.
Name
name
Type
string
Description
Display name for the app. Must not be empty after trimming whitespace.
Name
placement_parent_application_id
Type
string
Description
App under which to place the new child app. Defaults to the app that authenticates the request.
relationship_policyobjectOptional policy for the parent-child app relationship. Omitted fields use the defaults shown below.Click or tap to expand
- Name
  child_standing
  Type
  enum
  Description
  Standing of the child app. Supported values are controlled, temporary_setup, and independent. Defaults to controlled for parent-managed apps and independent for child-managed apps.
- Name
  credentials
  Type
  enum
  Description
  Which app controls credentials. Supported values are child and parent. Defaults to child.
- Name
  management
  Type
  enum
  Description
  Which app manages the relationship. Supported values are parent and child. Defaults to parent.

Response shape

The response returns a top-level app object. The object includes the new app ID, app metadata, creation timestamp, and a create-only secret_key object.

Response attributes

Name
alias
Type
string
Description
Short label stored for the app.
Name
created_at
Type
timestamp
Description
When the app was created.
Name
description
Type
string
Description
Description stored for the app.
Name
id
Type
string
Description
Unique app ID with the app_ prefix.
Name
name
Type
string
Description
Display name stored for the app.
relationshipobjectReceipt for the parent-child relationship created with the app.Click or tap to expand
- Name
  child_app_id
  Type
  string
  Description
  ID of the newly created child app.
- Name
  child_standing
  Type
  string
  Description
  Standing applied to the child app.
- Name
  created_at
  Type
  timestamp
  Description
  When the relationship was created.
- Name
  id
  Type
  string
  Description
  Unique identifier for the relationship.
- Name
  kind
  Type
  string
  Description
  Relationship kind.
- Name
  placement_parent_app_id
  Type
  string
  Description
  ID of the app under which the child was placed.
- Name
  policy_version
  Type
  string
  Description
  Version of the applied relationship policy.
- Name
  relationship_policy
  Type
  object
  Description
  Applied child_standing, credentials, and management values.
- Name
  status
  Type
  string
  Description
  Current relationship status.
secret_keyobjectInitial secret key for the new app. Returned only by this endpoint.Click or tap to expand
- Name
  id
  Type
  string
  Description
  Unique identifier for the secret key.
- Name
  issued_at
  Type
  timestamp
  Description
  When the secret key was issued.
- Name
  token
  Type
  string
  Description
  Bearer token value. Store this value immediately; it is returned only once.
- Name
  token_type
  Type
  string
  Description
  Token type. Currently bearer.

Request

POST

/apps/create

curl https://api.zebo.dev/apps/create \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "acme-prod-api",
    "description": "Production Commerce API for Acme Marketplace",
    "legal_entity_type": "business",
    "name": "Acme Production API"
  }'

{
  "app": {
    "alias": "acme-prod-api",
    "created_at": "2025-02-15T14:30:00Z",
    "description": "Production Commerce API for Acme Marketplace",
    "id": "app_F2gH4iJ6kL8mN0oP2qR4sT6uV8wX0yZ",
    "name": "Acme Production API",
    "relationship": {
      "child_app_id": "app_F2gH4iJ6kL8mN0oP2qR4sT6uV8wX0yZ",
      "child_standing": "controlled",
      "created_at": "2025-02-15T14:30:00Z",
      "id": "apprel_2xL4nP6rT8vX0zB2dF4hJ6lN8pR0tV2x",
      "kind": "placement",
      "placement_parent_app_id": "app_M8nP0qR2sT4uV6wX8yZ0aB2cD4eF6gH",
      "policy_version": "app_relationship_authority.v1",
      "relationship_policy": {
        "child_standing": "controlled",
        "credentials": "child",
        "management": "parent"
      },
      "status": "active"
    },
    "secret_key": {
      "id": "sk_Q1wE3rT5yU7iO9pA2sD4fG6hJ8kL0zX",
      "issued_at": "2025-02-15T14:30:00Z",
      "token": "<SECRET_KEY_TOKEN>",
      "token_type": "bearer"
    }
  }
}

Lookup an app

Retrieve the app associated with the API key used on the request. Use this endpoint to confirm which app a secret key authenticates as, or to display app metadata in your own tooling.

The request has no body. The response includes app metadata only; it does not include secret key values.

Request attributes

No request body is required.

Response shape

The response returns a top-level app object for the authenticated app.

Response attributes

Name
alias
Type
string
Description
Short label stored for the app.
Name
archived_at
Type
timestamp
Description
When the app was archived. Null while the app is active.
Name
created_at
Type
timestamp
Description
When the app was created.
Name
description
Type
string
Description
Description stored for the app.
Name
id
Type
string
Description
Unique app ID with the app_ prefix.
Name
name
Type
string
Description
Display name stored for the app.
Name
updated_at
Type
timestamp
Description
When the app metadata was last updated. Null if the app has not been updated.

Request

POST

/apps/lookup

curl -X POST https://api.zebo.dev/apps/lookup \
  -H "Authorization: Bearer $COMMERCE_API_KEY"

{
  "app": {
    "alias": "acme-prod-api",
    "created_at": "2025-02-15T14:30:00Z",
    "description": "Production Commerce API for Acme Marketplace",
    "id": "app_F2gH4iJ6kL8mN0oP2qR4sT6uV8wX0yZ",
    "name": "Acme Production API",
    "updated_at": "2025-02-16T09:45:30Z"
  }
}

Update an app

Update metadata for the app associated with the API key used on the request. This endpoint changes app labels and classification; it does not rotate secret keys or move resources between apps.

Send at least one mutable attribute. Empty alias and description values clear those fields. Empty name is rejected.

Request attributes

Name
alias
Type
string
Description
New short label for the app. Send an empty string to clear it.
Name
description
Type
string
Description
New app description. Send an empty string to clear it.
Name
legal_entity_type
Type
string
Description
Legal-entity classification. The API trims surrounding whitespace and stores the supplied string.
Name
name
Type
string
Description
New display name for the app. Must not be empty after trimming whitespace.

Response shape

The response returns a top-level app object with the current metadata after the update.

Response attributes

Name
alias
Type
string
Description
Short label stored for the app.
Name
created_at
Type
timestamp
Description
When the app was created.
Name
description
Type
string
Description
Description stored for the app.
Name
id
Type
string
Description
Unique app ID with the app_ prefix.
Name
name
Type
string
Description
Display name stored for the app.
Name
updated_at
Type
timestamp
Description
When the app metadata was last updated.

Request

POST

/apps/update

curl https://api.zebo.dev/apps/update \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Idempotency-Key: app-update-acme-checkout-001" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "acme-checkout-api",
    "description": "Checkout API for Acme Marketplace",
    "legal_entity_type": "business",
    "name": "Acme Checkout API"
  }'

Reuse the same Idempotency-Key value when retrying the same update after a timeout or network failure. A different key starts a new update operation.

{
  "app": {
    "alias": "acme-checkout-api",
    "created_at": "2025-02-15T14:30:00Z",
    "description": "Checkout API for Acme Marketplace",
    "id": "app_F2gH4iJ6kL8mN0oP2qR4sT6uV8wX0yZ",
    "name": "Acme Checkout API",
    "updated_at": "2025-02-16T09:45:30Z"
  }
}