---
title: "Get an application"
method: GET
path: "/v1/applications/{appId}"
tags: ["Applications"]
---

# Get an application

`GET /v1/applications/{appId}`

## Request

- Base URL: `https://api.prod.keyban.io`
- URL: `https://api.prod.keyban.io/v1/applications/{appId}`
- Auth: API key in header `X-Api-Key`

Fetch a specific application by ID to inspect its configuration or attach downstream resources.

## Path parameters

- `appId` string, uuid, required

## Response `200`

Application retrieved successfully

- ApplicationDtoOutput: An application is a Keyban application. It is required to use the SDK and the API endpoints. It serves as the entry point to access and interact with the Keyban platform.
  - `id` string, uuid, required: Entity UUID
  - `createdAt` string, date-time, required: Creation date (ISO 8601)
  - `updatedAt` string, date-time, required: Last update date (ISO 8601)
  - `organization` object, required
    - `id` string, uuid, required: Unique identifier of the organization (UUID v4).
    - `createdAt` string, date-time, required: Creation date (ISO 8601).
    - `name` string, required: Legal or commercial name of the organization (e.g. `Keyban SAS`). Displayed in the admin UI and on invoices.
    - `slug` string, required: URL-safe unique identifier of the organization in kebab-case (e.g. `keyban-sas`). Used in API paths and subdomains. Distinct from `name`.
    - `logo` string, uri, nullable, required: HTTPS URL of the organization logo (PNG or SVG). `null` when no logo has been uploaded.
    - `defaultLocale` 'en-US' | 'fr-FR' | 'es-ES' | 'it-IT' | 'null', nullable: BCP 47 language tag for the organization's default locale (e.g. `fr-FR`). Null when not set; falls back to Accept-Language header.
    - `preferredCurrency` 'EUR' | 'USD' | 'JPY' | 'null', nullable: Fiat currency (ISO 4217) the organization displays monetary values in: wallet and treasury balances are converted to it, transfer amounts are quoted in it for signers, and agent spending policies are authored in it. Chosen once, at the creation of the first application or treasury, and immutable afterwards (a change is refused with `ORG_PREFERRED_CURRENCY_IMMUTABLE`; sending `null` or omitting the field leaves it untouched). Null until chosen.
    - `agentRoles` string[], nullable: What the organization's agents do, as picked during the agent-wallet onboarding. Selects the example prompts offered for the first payment. Null until picked.
    - `acquisitionChannel` 'n8n' | 'trial' | 'null', nullable: Third-party channel the organization signed up through (e.g. the n8n node listing). Null for an organic/direct signup, never attributed to a specific channel.
    - `settings` object, required
      - `authConfig` object, required
        - `email-otp` union, required
          - object
            - `enabled` true, required: Authentication method is active for this organization.
          - object
            - `enabled` false, required: Authentication method is disabled for this organization.
        - `phone-otp` union, required
          - object
            - `enabled` true, required: Authentication method is active for this organization.
          - object
            - `enabled` false, required: Authentication method is disabled for this organization.
        - `google` union, required
          - object
            - `enabled` true, required: Authentication method is active for this organization.
          - object
            - `enabled` false, required: Authentication method is disabled for this organization.
        - `auth0` union, required
          - object
            - `enabled` true, required: Authentication method is active for this organization.
            - `clientId` string, required: OAuth 2.0 / OIDC client identifier issued by the Auth0 tenant. Required when Auth0 is enabled.
            - `domain` string, required: Auth0 tenant domain used as the OIDC issuer base URL (e.g. `keyban.eu.auth0.com`). Required when Auth0 is enabled.
          - object
            - `enabled` false, required: Authentication method is disabled for this organization.
  - `name` string, required: Human-readable name of the application.
  - `slug` string, required: URL-safe identifier of the application (kebab-case, unique within the organization). Used in URLs and API paths.
  - `features` string[], required: List of enabled features for this application.
  - `domains` string[], required: List of authorized domains for this application.
  - `websiteUrl` union: Public website URL.
    - string, uri
    - ''
  - `preferredCurrency` 'EUR' | 'USD' | 'JPY' | 'null', nullable, required: Fiat currency (ISO 4217) the application displays monetary values in: wallet balances are converted to it, and spending policies are authored in it. Read-only mirror of the organization's `preferredCurrency`, chosen once for the whole organization. Null until the organization picks it.
  - `network` 'EthereumAnvil' | 'BaseSepolia' | 'BaseMainnet' | 'XdcApothem' | 'XdcMainnet' | 'StellarQuickstart' | 'StellarTestnet' | 'StellarMainnet' | 'null', nullable, required: Blockchain network the application runs on. One network per application: agent wallets, balances and spending policies all assume a single chain, and creating a wallet on another network is rejected. Declared once from the agent-wallet onboarding step of the dashboard, then immutable — its wallets are deployed on that chain, so changing it would orphan them; a different network means a different application. The declaration is also checked against the organization quota (`allowedNetworks`). Null on applications that never declared it.
  - `theme` object, required: Visual branding configuration for the application, including appearance (colors, fonts, images) and page metadata.
    - `title` string: Title for the application.
    - `mode` 'light' | 'dark'
    - `primaryColor` string
    - `secondaryColor` string
    - `logoUrl` union: URL for the logo image. Supported format: PNG. Recommended size: 512×512 px (square). Max file size: 500 KB.
      - string, uri
      - ''
    - `bgImageUrl` union: URL for the background image. Supported format: PNG. Recommended size: 1920×1080 px (landscape). Max file size: 1 MB.
      - string, uri
      - ''
    - `googleFont` string: Google Font name to be used.
    - `customFontUrl` union: Optional font URL. When provided, the loyalty app will use this font file (even if a Google font is specified).
      - string, uri
      - ''
  - `dppSettings` object, nullable, required: Digital Product Passport application configuration, including token contracts and action endpoints.
    - `tokens` object[], required: Token contracts available for the application, across all enabled networks. At least one per supported network should be configured.
      - `network` 'EthereumAnvil' | 'BaseSepolia' | 'BaseMainnet' | 'XdcApothem' | 'XdcMainnet' | 'StellarQuickstart' | 'StellarTestnet' | 'StellarMainnet', required: Blockchain network where the token contract is deployed. DPP token contracts are EVM-only (e.g. BaseMainnet).
      - `address` string, required: Blockchain address of the token contract on the specified network (EVM checksummed 0x... address).
      - `name` string, required: Human-readable token name (e.g., "DPP Certification Token"). Displayed on explorers and wallets.
      - `symbol` string, required: Token symbol, typically uppercase and under 10 characters (e.g., "DPP", "CERT"). Used for brevity on UI.
    - `actions` object[], required: Public action buttons rendered on the passport viewer page (e.g. authenticity proof link, care guide). Each action appears as a clickable button under the passport.
      - `id` string, uuid, required: Stable UUID v4 assigned server-side. Unique per application. Used to identify and update a specific action button.
      - `enabled` boolean, required: When `false`, the button is hidden on the public passport viewer. The `url` and `icon` fields are ignored.
      - `type` 'circularity' | 'marketing', required: Functional family of the action. The passport viewer renders one card per type (circularity services vs commercial offers).
      - `url` string: Absolute HTTPS URL the button points to. When empty or absent, the action is rendered as a non-clickable informational row on the passport viewer.
      - `label` object: Localized label displayed on the button, keyed by BCP 47 locale code. The DPP App resolves the active locale and falls back to the application default locale. The button is hidden when no label matches.
      - `description` object: Localized secondary line displayed under the label on the passport viewer, keyed by BCP 47 locale code (e.g. the program or offer the action belongs to). Resolved with the same locale rules as `label`. The line is omitted when absent.
      - `icon` string: Icon identifier for the button. Accepts a Lucide icon name in kebab-case (e.g. `"recycle"`, `"wrench"` — the viewer supports a curated subset and renders unknown names as plain text, so emojis also work) or an absolute HTTPS URL pointing to an SVG asset.
    - `heroTitle` object, nullable: Localized headline shown in the passport viewer hero, keyed by BCP 47 locale. When set, it replaces the built-in default copy on both the product (model) and item passport heroes. The DPP App resolves the active locale and falls back to the application default locale; the hero title is hidden when no value matches.
    - `heroSubtitle` object, nullable: Localized sub-headline shown under the hero title in the passport viewer, keyed by BCP 47 locale. Resolved with the same locale rules as `heroTitle`. Hidden when no value matches the active or default locale.
  - `loyaltySettings` object, nullable, required: Global configuration schema for a loyalty program, including earning/redeeming rules, associated token, and visual customizations.
    - `currency` 'EUR' | 'USD': Currency used to express the monetary value of loyalty points
    - `visitsWindowDays` integer: Sliding window in days used to evaluate loyalty tier progression. At most one visit is counted per day (multiple purchases in the same day count as one). If a higher tier is defined, customers may be auto-upgraded based on visits within this period.
    - `currencyToPointRatio` integer: Number of loyalty points earned for each 1 unit of currency spent (e.g., if the ratio is 2 and currency is EUR, spending €1 earns 2 points). Used to calculate point accruals from transaction amounts.
    - `pointsConversionThreshold` integer: Minimum number of points required to unlock a fixed monetary discount. Redemption is available only once the threshold is reached and can then be applied in multiples of this threshold (e.g., with threshold = 100, 200 points can redeem 2× the discount).
    - `pointsConversionThresholdValue` integer: Monetary discount granted each time the threshold is redeemed, expressed in the selected currency. Example: threshold = 100 and value = 5 ⇒ 100 pts → 5 (currency units), 200 pts → 10, etc. No partial redemption occurs below the threshold.
    - `welcomeBonus` integer: Applied to the customer's first purchase. Equivalent to the monetary amount at the current conversion rate.
    - `tokens` object[], required: Blockchain tokens representing loyalty points associated with the program.
      - `network` 'EthereumAnvil' | 'BaseSepolia' | 'BaseMainnet' | 'XdcApothem' | 'XdcMainnet' | 'StellarQuickstart' | 'StellarTestnet' | 'StellarMainnet', required: Blockchain network where the loyalty token contract is deployed.
      - `address` string, required: Blockchain address of the token contract on the specified network. Format: network-specific (EVM checksummed 0x..., Stellar native asset code).
      - `name` string, required: Human-readable token name shown on explorers and wallets (e.g., "Acme Loyalty Points").
      - `symbol` string, required: Token symbol, typically uppercase and under 10 characters (e.g., "ACME-LP"). Used for brevity on UI.
    - `app` object, required: Configuration for the loyalty application, including appearance (colors, fonts, images) and page metadata.
      - `pointName` string, nullable: Human-readable name for a single loyalty point (e.g., “point”, “mile”, “star”).
      - `pointSymbol` string, nullable: Short symbol for the loyalty point (e.g., “pt”, “⭐”).
      - `onboarding` object, required: Onboarding flow configuration, including welcome messages, carousel, and visual styling.
        - `showTexts` boolean: When `true`, onboarding text blocks (title, subtitle) are displayed on the customer welcome screen.
        - `fontColor` string, nullable: HEX color code applied to all onboarding text, allowing brand-consistency without requiring multiple asset versions. `null` when left at the default text color.
        - `title` string, nullable: Primary heading shown during onboarding (e.g., "Welcome to our loyalty program"). `null`/omitted when no custom title is set.
        - `subtitle` string, nullable: Secondary heading or introductory message displayed under the title. `null`/omitted when no subtitle is set.
        - `qrCodeText` string, nullable: Label displayed alongside the QR code that links the customer to the loyalty app or claim page. `null`/omitted when no custom label is set.
        - `bgImageUrl` string, uri, nullable: URL for the onboarding background image. Supported format: PNG. Recommended size: 1920×1080 px (landscape). Max file size: 1 MB.
        - `carousel` object: Onboarding carousel configuration, including slide images and auto-play interval. Omitted when no carousel is desired.
          - `interval` number, required: Time in milliseconds between automatic carousel slides (e.g., `5000` for 5 seconds). Used only when the carousel is in auto-play mode.
          - `images` object[], required: Ordered list of carousel slides shown during onboarding.
            - `url` string, required: URL for carousel image. Supported format: PNG. Recommended size: 800×600 px (4:3 ratio). Max file size: 300 KB.
            - `title` string, nullable: Short caption shown above or overlaid on the carousel slide. `null`/omitted when the slide has no caption.
            - `description` string, nullable: Longer text describing the slide content, displayed below or beside the image. `null`/omitted when the slide has no description.
    - `googleWallet` object, nullable: Google Wallet configuration for loyalty card issuance. When omitted or `null`, the loyalty app does not support Google Wallet integration.
      - `logoUrl` string, uri, required: URL for Google Wallet logo. Supported format: PNG. Minimum dimensions: 660×660 px (square). Max file size: 500 KB. Keep key elements within a safe zone (15% margin) due to circular masking.
      - `title` string, required: Display name of the loyalty card shown in the Google Wallet pass list (e.g., "Acme Rewards").
      - `header` string, required: Header text displayed at the top of the loyalty card face (e.g., program name or subtitle).
      - `bgColor` string, nullable: Background color of the card face, as a HEX code. Fallback when `bgImageUrl` is not provided. `null` when left at the Wallet default.
      - `bgImageUrl` string, uri, nullable: URL for Google Wallet background image. Supported format: PNG (mandatory). Recommended dimensions: 1032×336 px (3:1 ratio). Maximum file size: 5 MB.
      - `detailsHeader` string, nullable: Section heading shown in the card details view (e.g., "Your Balance"). Limited to brief labels due to space constraints. `null`/omitted when no details section is configured.
      - `detailsBody` string, nullable: Body text in the card details view (e.g., account number, current balance, program tier). Supports multi-line content. `null`/omitted when no details section is configured.
    - `appleWallet` object, nullable: Apple Wallet configuration for loyalty card issuance. When omitted or `null`, the loyalty app does not support Apple Wallet integration.
      - `logoUrl` string, uri, required: URL for Apple Wallet logo. Supported format: PNG only. Recommended sizes: 160×50 (1x), 320×100 (2x), 480×150 (3x). Max file size: 100 KB.
      - `iconUrl` string, uri, required: URL for Apple Wallet icon (shown in Wallet app icon picker). Supported format: PNG only. Recommended sizes: 29×29 (1x), 58×58 (2x), 87×87 (3x). Max file size: 100 KB.
      - `title` string, nullable: Optional short text shown next to the logo in the Wallet app (e.g., "Acme Rewards Card"). `null`/omitted when the pass should display the logo only.
      - `labelColor` string, nullable: Color applied to field labels (e.g., "Balance", "Member ID") on the pass, as a HEX code. Improves readability against the background. `null` when left at the Wallet default.
      - `fgColor` string, nullable: Foreground (text) color of dynamic pass content, as a HEX code. Used for balance amounts and other variable data. `null` when left at the Wallet default.
      - `bgColor` string, nullable: Background color of the pass strip, as a HEX code. Fallback when `bgImageUrl` is not provided. `null` when left at the Wallet default.
      - `bgImageUrl` string, uri, nullable: URL for Apple Wallet background image (strip). Supported format: PNG only. Recommended sizes: 624×168 (2x), 936×252 (3x). Max file size: 100 KB.
  - `shopifyShop` object, nullable
    - `id` string, uuid, required: Entity UUID
    - `createdAt` string, date-time, required: Creation date (ISO 8601)
    - `updatedAt` string, date-time, required: Last update date (ISO 8601)
    - `network` 'EthereumAnvil' | 'BaseSepolia' | 'BaseMainnet' | 'XdcApothem' | 'XdcMainnet' | 'StellarQuickstart' | 'StellarTestnet' | 'StellarMainnet', required
    - `name` string, required: Display name of the shopify shop
    - `domain` string, required: Display domain of the shopify shop
    - `hasSession` boolean, required
  - `cloudflareSession` object, nullable

---

[API](https://skmtc.dev/keyban/apis/keyban-rest-apis.md) · [All operations](https://skmtc.dev/keyban/apis/keyban-rest-apis/llms.txt) · [OpenAPI document](https://skmtc.dev/keyban/apis/keyban-rest-apis/revisions/0bb79a1da961?raw)