Embedded integration overview

Embedded mode lets end users view balance, usage, and entitlements and call authorized model capabilities inside your app. Your App backend identifies the user and exchanges a short-lived token; browsers and mobile apps never receive the AppClient secret.

sequenceDiagram
    participant U as Client app
    participant A as App backend
    participant C as AI Credits
    U->>A: Authenticated app session
    A->>C: Basic credential + pseudonymous external_user_id
    C-->>A: Short-lived opaque token
    A-->>U: Token over protected session
    U->>C: Bearer token to /users/me/* or data API
    C-->>U: Current-user-scoped result

Security boundaries

• Keep the AppClient secret only in the App backend's Secret Manager and necessary process memory.
• Make external_user_id an Application-scoped pseudonymous identifier, never an email address, phone number, or username.
• Clients hold only short-lived opaque tokens. SDKs do not persist, log, or refresh them automatically.
• Bind the Application code when constructing the client so it can access only its own /users/me/* resources.
• Money, Credits, rates, and billed values are decimal strings. Do not convert them to binary floating-point values.

Integration order

1. Implement token exchange in the App backend.
2. Select the TypeScript, Swift, or Kotlin SDK and provide secure token storage.
3. Integrate the self-service API and data API as needed.
4. For server events, verify the raw request as described in webhooks.
5. Cover isolation, expiry, revocation, and replay with the testing checklist.

In-app purchases and ready-made UI components are not yet delivered. See the current status of store purchases and UI guidelines.