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.
Operations
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
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 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.
Surrounding whitespace is removed from text attributes, and unknown attributes are rejected. name must remain non-empty after trimming. For legal_entity_type, use government, non_profit, business, or individual; integrations should not rely on undocumented classifications being accepted.
Omit placement_parent_application_id for ordinary child-app creation. Placing the child under another app requires a valid authorization receipt for that relationship and a compatible relationship_policy; a bare parent ID is rejected with 422.
Request attributes
Response shape
A successful response returns 200 with a top-level app object. It includes the new app ID, stored metadata, creation timestamp, a placement relationship receipt, and a create-only secret_key. Invalid JSON, missing or unknown attributes, unsupported relationship policy values, and unauthorized placement return 422; missing or invalid authentication returns 401.
Optional app attributes are omitted when empty. Although secret_key is expected for normal public creation, clients must still check that it is present before attempting to store the token.
Response attributes
Request
- cURL
- TypeScript
- Go
- Python
- PHP
- Ruby
- Java
- C#
curl https://api.inttegro.com/apps/create \
-H "Authorization: Bearer $INTTEGRO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"alias": "acme-prod-api",
"description": "Production Inttegro API for Acme Marketplace",
"legal_entity_type": "business",
"name": "Acme Production API"
}'
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",
})
package main
import (
"context"
"log"
"os"
inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
)
func main() {
ctx := context.Background()
client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY"))
params := inttegro.CreateAppParams{
Alias: "acme-prod-api",
Description: "Production Inttegro API for Acme Marketplace",
LegalEntityType: "business",
Name: "Acme Production API",
}
result, err := client.Apps.Create(ctx, params)
if err != nil {
log.Fatal(err)
}
_ = result
}
import os
import inttegro
client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
result = client.apps.create(inttegro.apps.CreateRequest(
alias="acme-prod-api",
description="Production Inttegro API for Acme Marketplace",
legal_entity_type="business",
name="Acme Production API",
))
<?php
use Inttegro\Client;
$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->apps->create([
'alias' => 'acme-prod-api',
'description' => 'Production Inttegro API for Acme Marketplace',
'legal_entity_type' => 'business',
'name' => 'Acme Production API',
]);
require "inttegro"
client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.apps.create(
alias: "acme-prod-api",
description: "Production Inttegro API for Acme Marketplace",
legal_entity_type: "business",
name: "Acme Production API"
)
import com.inttegro.Client;
import com.inttegro.apps.CreateAppParams;
public class Example {
public static void main(String[] args) throws Exception {
var client = new Client(System.getenv("INTTEGRO_API_KEY"));
var params = CreateAppParams.builder()
.alias("acme-prod-api")
.description("Production Inttegro API for Acme Marketplace")
.legalEntityType("business")
.name("Acme Production API")
.build();
var result = client.apps().create(params);
}
}
using Inttegro;
using var inttegro = new InttegroClient(
Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.Apps.CreateAsync(new {
alias = "acme-prod-api",
description = "Production Inttegro API for Acme Marketplace",
legal_entity_type = "business",
name = "Acme Production API",
});
Response
- Object
- JSON
AppResponse {
app: { … },
}
{
"app": {
"alias": "acme-prod-api",
"created_at": "2025-02-15T14:30:00Z",
"description": "Production Inttegro API for Acme Marketplace",
"id": "app_F2gH4iJ6kL8mN0oP2qR4sT6uV8wX0yZ",
"name": "Acme Production API",
"relationship": { … },
"secret_key": { … }
}
}
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 only; it never includes secret key values.
Request attributes
No request body is required.
Response shape
The response returns your current app as a top-level app object.
Response attributes
Request
- cURL
- TypeScript
- Go
- Python
- PHP
- Ruby
- Java
- C#
curl -X POST https://api.inttegro.com/apps/lookup \
-H "Authorization: Bearer $INTTEGRO_API_KEY"
import * as Inttegro from '@inttegro/inttegro-sdk'
const inttegro = new Inttegro.InttegroClient({
apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.apps.lookup()
package main
import (
"context"
"log"
"os"
inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
)
func main() {
ctx := context.Background()
client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY"))
result, err := client.Apps.Lookup(ctx)
if err != nil {
log.Fatal(err)
}
_ = result
}
import os
import inttegro
client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
result = client.apps.lookup()
<?php
use Inttegro\Client;
$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->apps->lookup();
require "inttegro"
client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.apps.lookup
import com.inttegro.Client;
public class Example {
public static void main(String[] args) throws Exception {
var client = new Client(System.getenv("INTTEGRO_API_KEY"));
var result = client.apps().lookup();
}
}
using Inttegro;
using var inttegro = new InttegroClient(
Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.Apps.LookupAsync();
Response
- Object
- JSON
AppResponse {
app: { … },
}
{
"app": {
"alias": "acme-prod-api",
"created_at": "2025-02-15T14:30:00Z",
"description": "Production Inttegro 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. Unknown attributes are rejected. Text values are trimmed; empty alias, description, and legal_entity_type values clear those fields, while an empty name is rejected. Sending values that are already stored succeeds without changing updated_at.
A successful update returns 200; invalid JSON, an empty update, unknown attributes, or a failed update returns 422, and missing or invalid authentication returns 401.
Request attributes
Response shape
The response returns a top-level app object with the current metadata after the update.
Response attributes
Request
- cURL
- TypeScript
- Go
- Python
- PHP
- Ruby
- Java
- C#
curl https://api.inttegro.com/apps/update \
-H "Authorization: Bearer $INTTEGRO_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"
}'
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",
})
package main
import (
"context"
"log"
"os"
inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
)
func main() {
ctx := context.Background()
client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY"))
params := inttegro.UpdateAppParams{
Alias: inttegro.String("acme-checkout-api"),
Description: inttegro.String("Checkout API for Acme Marketplace"),
LegalEntityType: inttegro.String("business"),
Name: inttegro.String("Acme Checkout API"),
}
result, err := client.Apps.Update(ctx, params, inttegro.WithIdempotencyKey("app-update-acme-checkout-001"))
if err != nil {
log.Fatal(err)
}
_ = result
}
import os
import inttegro
client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
result = client.apps.update(inttegro.apps.UpdateRequest(
alias="acme-checkout-api",
description="Checkout API for Acme Marketplace",
legal_entity_type="business",
name="Acme Checkout API",
))
<?php
use Inttegro\Client;
$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->apps->update([
'alias' => 'acme-checkout-api',
'description' => 'Checkout API for Acme Marketplace',
'legal_entity_type' => 'business',
'name' => 'Acme Checkout API',
]);
require "inttegro"
client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.apps.update(
alias: "acme-checkout-api",
description: "Checkout API for Acme Marketplace",
legal_entity_type: "business",
name: "Acme Checkout API"
)
import com.inttegro.Client;
import com.inttegro.apps.UpdateAppParams;
import com.inttegro.RequestOptions;
public class Example {
public static void main(String[] args) throws Exception {
var client = new Client(System.getenv("INTTEGRO_API_KEY"));
var params = UpdateAppParams.builder()
.alias("acme-checkout-api")
.description("Checkout API for Acme Marketplace")
.legalEntityType("business")
.name("Acme Checkout API")
.build();
var result = client.apps().update(params, RequestOptions.withIdempotencyKey("app-update-acme-checkout-001"));
}
}
using Inttegro;
using var inttegro = new InttegroClient(
Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.Apps.UpdateAsync(new {
alias = "acme-checkout-api",
description = "Checkout API for Acme Marketplace",
legal_entity_type = "business",
name = "Acme Checkout API",
});
Response
- Object
- JSON
AppResponse {
app: { … },
}
{
"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"
}
}