Apps

An app is an Inttegro account. It represents the business, seller, sales channel, tenant, or environment that is selling, collecting payments, messaging customers, and receiving payouts through Inttegro.

Everything that happens for that account belongs to its app: orders, customers, payment methods, balances, payouts, files, and customer messages. This keeps each business unit or tenant in its own operating boundary, so records, reconciliation, and access do not bleed across accounts.

Apps also have secret keys. When your backend uses a key, it is acting for that app. Use the Apps API when you need to create or manage Inttegro accounts programmatically: onboarding a merchant or tenant, separating production from staging, isolating a sales channel, or giving a child integration its own credentials. Do not create apps for individual shoppers, orders, devices, or checkout sessions.

The app object

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

Properties

TypeScript SDK responseAppv12.0.0

Name
alias
Type
string
Description
Optional short label for the app. Use this for names that are easier to scan in dashboards, logs, or developer tooling than the generated app ID.
Name
archivedAt
Type
Date
Description
When the app was archived. Omitted while the app is active.
capabilitiesRecord<string, unknown>Click or tap to expand
Public capability states currently available to this app. New capability keys can appear as more Inttegro products become available.
Name
createdAt
Type
Date
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.
relationshipAppRelationshipDirect placement for this app. Omitted for root apps.Click or tap to expand
- Name
  createdAt
  Type
  Date
  Description
  When the relationship was created.
- Name
  id
  Type
  string
  Description
  Unique identifier for the relationship.
- Name
  kind
  Type
  AppRelationshipKind
  Description
  Relationship kind.
- Name
  parent
  Type
  AppRelationshipParent
  View parent detailsClick or tap to expand
  The app that directly contains this app, including its ID, current name, and optional alias.
- Name
  status
  Type
  AppRelationshipStatus
  Description
  Current relationship status.
Name
updatedAt
Type
Date
Description
When the app metadata was last updated. Omitted until the first update.

POST/apps/create

Create an app

Create an Inttegro child app and its first secret key. Your current Inttegro account becomes its parent unless you supply separately authorized delegated placement details.

Store secretKey.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.

Surrounding whitespace is removed from text attributes, and unknown attributes are rejected. name must remain non-empty after trimming. For legalEntityType, use "government", "non_profit", "business", or "individual"; integrations should not rely on undocumented classifications being accepted.

Omit placementParentApplicationId for ordinary child-app creation. Placing the child under another app requires a valid authorization receipt for that relationship and a compatible relationshipPolicy; a parent ID alone is not sufficient.

Request attributes

TypeScript SDK requestCreateAppRequestv12.0.0

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
legalEntityType
Type
string
Description
Optional legal-entity classification. The API trims surrounding whitespace and stores the supplied string.
Name
name
Type
string
Required
required
Description
Display name for the app. Must not be empty after trimming whitespace.
Name
placementParentApplicationId
Type
string
Description
App under which to place the new child app. Omit this to use the app that authenticates the request. A different parent requires separately authorized delegated placement details.
relationshipPolicyAppRelationshipPolicyOptional policy for the parent-child app relationship. Omitted fields use the defaults shown below.Click or tap to expand
- Name
  childStanding
  Type
  string
  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
  AppCredentialOwner
  Description
  Which app controls credentials. Supported values are Inttegro.AppCredentialOwners.Child and Inttegro.AppCredentialOwners.Parent. Defaults to Inttegro.AppCredentialOwners.Child.
- Name
  management
  Type
  AppManagementRole
  Description
  Which app manages the relationship. Supported values are Inttegro.AppManagementRoles.Parent and Inttegro.AppManagementRoles.Child. Defaults to Inttegro.AppManagementRoles.Parent.

Response shape

The response contains the new App, its placement relationship, and a create-only secretKey.

Optional app attributes are omitted when empty. Although secretKey is expected for normal public creation, clients must still check that it is present before attempting to store the token.

Response attributes

TypeScript SDK responseAppv12.0.0

Name
alias
Type
string
Description
Short label stored for the app.
Name
createdAt
Type
Date
Description
When the app was created.
capabilitiesRecord<string, unknown>Click or tap to expand
Capability states available immediately after creation. New apps can return an empty object until capabilities become available.
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.
relationshipAppRelationshipDirect placement created for the new app.Click or tap to expand
- Name
  createdAt
  Type
  Date
  Description
  When the relationship was created.
- Name
  id
  Type
  string
  Description
  Unique identifier for the relationship.
- Name
  kind
  Type
  AppRelationshipKind
  Description
  Relationship kind.
- Name
  parent
  Type
  AppRelationshipParent
  View parent detailsClick or tap to expand
  The app that directly contains the new app, including its ID, current name, and optional alias.
- Name
  status
  Type
  AppRelationshipStatus
  Description
  Current relationship status.
secretKey{ … }Initial 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
  issuedAt
  Type
  Date
  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
  tokenType
  Type
  string
  Description
  Token type. Currently "bearer".

Request

POST/apps/create

SDK versionv12.0.0

import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.apps.create({
  alias: "acme-prod-api",
  description: "Production Inttegro API for Acme Marketplace",
  legalEntityType: "business",
  name: "Acme Production API",
})

Response

Object
JSON

SDK versionv12.0.0

AppResponse {
  app: { … },
}

SDK versionv12.0.0

{
  "app": {
    "alias": "acme-prod-api",
    "capabilities": {},
    "created_at": "2025-02-15T14:30:00Z",
    "description": "Production Inttegro API for Acme Marketplace",
    "id": "app_F2gH4iJ6kL8mN0oP2qR4sT6uV8wX0yZ",
    "name": "Acme Production API",
    "relationship": { … },
    "secret_key": { … }
  }
}

POST/apps/lookup

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. An empty JSON object is also accepted. Unknown attributes are rejected. The response includes app metadata and, for a child app, its direct placement relationship. It never includes secret key values.

Request attributes

No request body is required.

Response shape

The response returns App for your current account. Child apps include relationship; root apps omit it.

Response attributes

TypeScript SDK responseAppv12.0.0

Name
alias
Type
string
Description
Short label stored for the app.
Name
archivedAt
Type
Date
Description
When the app was archived. Omitted while the app is active.
Name
createdAt
Type
Date
Description
When the app was created.
capabilitiesRecord<string, unknown>Click or tap to expand
Public capability states currently available to the app. Read only the keys your integration understands and allow new keys to appear.
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.
relationshipAppRelationshipDirect placement for the authenticated app. Omitted for root apps.Click or tap to expand
- Name
  createdAt
  Type
  Date
  Description
  When the relationship was created.
- Name
  id
  Type
  string
  Description
  Unique identifier for the relationship.
- Name
  kind
  Type
  AppRelationshipKind
  Description
  Relationship kind.
- Name
  parent
  Type
  AppRelationshipParent
  View parent detailsClick or tap to expand
  The app that directly contains this app, including its ID, current name, and optional alias.
- Name
  status
  Type
  AppRelationshipStatus
  Description
  Current relationship status.
Name
updatedAt
Type
Date
Description
When the app metadata was last updated. Omitted until the first update.

Request

POST/apps/lookup

SDK versionv12.0.0

import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.apps.lookup()

Response

Object
JSON

SDK versionv12.0.0

AppResponse {
  app: { … },
}

SDK versionv12.0.0

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

POST/apps/update

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. Unknown attributes are rejected. Text values are trimmed; empty alias, description, and legalEntityType values clear those fields, while an empty name is rejected.

Sending values that are already stored succeeds without changing updatedAt.

Request attributes

TypeScript SDK requestUpdateAppRequestv12.0.0

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
legalEntityType
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 App with the current metadata after the update.

Response attributes

TypeScript SDK responseAppv12.0.0

Name
alias
Type
string
Description
Short label stored for the app.
Name
createdAt
Type
Date
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
updatedAt
Type
Date
Description
When the app metadata was last updated.

Request

POST/apps/update

SDK versionv12.0.0

import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.apps.update({
  alias: "acme-checkout-api",
  description: "Checkout API for Acme Marketplace",
  legalEntityType: "business",
  name: "Acme Checkout API",
})

Response

Object
JSON

SDK versionv12.0.0

AppResponse {
  app: { … },
}

SDK versionv12.0.0

{
  "app": {
    "alias": "acme-checkout-api",
    "capabilities": { … },
    "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"
  }
}

The app object

Properties​

Create an app

Request attributes​

Response shape​

Response attributes​

Request

Response

Lookup an app

Request attributes​

Response shape​

Response attributes​

Request

Response

Update an app

Request attributes​

Response shape​

Response attributes​

Request

Response

Properties

Request attributes

Response shape

Response attributes

Request attributes

Response shape

Response attributes

Request attributes

Response shape

Response attributes