> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# App Integration Quickstart

> Get your app connected to Profy in 5 minutes: create an app, OAuth authorization, report events, and bill users.

# Quickstart

This guide walks you through integrating with Profy: create an app → user authorization → report billing events.

## Prerequisites

* A Profy account with creator access
* Node.js >= 18

## Step 1: Create an App

1. Go to [Profy Studio](https://app.profy.cn/studio/works?tab=app)
2. Click "Create App" and enter your app name
3. Save your **App ID** and **App Secret**

<Warning>
  App Secret is only shown in full once. Store it securely and never commit it to version control.
</Warning>

## Step 2: Configure Redirect URI

In your app management page → Dev Config → Redirect URIs, add your callback URL.

* Production must use HTTPS
* `http://localhost` is allowed for local development

```
http://localhost:5180/callback
```

## Step 3: Install the SDK

<CodeGroup>
  ```bash npm theme={null}
  npm install @profy-ai/sdk
  ```

  ```bash bun theme={null}
  bun add @profy-ai/sdk
  ```

  ```bash Python theme={null}
  pip install profy-sdk
  # With optional SQLAlchemy auto-table support:
  pip install profy-sdk[sqlalchemy]
  ```
</CodeGroup>

## Step 4: Initiate OAuth Authorization

Redirect the user to Profy's authorization page:

```
https://app.profy.cn/oauth/authorize?client_id={APP_ID}&redirect_uri={CALLBACK_URL}&scope=events:write&response_type=code
```

| Parameter       | Description                                      |
| --------------- | ------------------------------------------------ |
| `client_id`     | Your App ID                                      |
| `redirect_uri`  | Must match what you registered                   |
| `scope`         | Requested permissions. Currently: `events:write` |
| `response_type` | Must be `code`                                   |

After the user approves, Profy redirects to your callback URL with an authorization code:

```
http://localhost:5180/callback?code=abc123...
```

## Step 5: Exchange Code for Token

In your backend, use the SDK to exchange the authorization code for an Access Token:

```typescript theme={null}
import { ProfyApp } from "@profy-ai/sdk";

const profy = new ProfyApp({
  clientId: process.env.PROFY_APP_ID,
  clientSecret: process.env.PROFY_APP_SECRET,
});

const token = await profy.exchangeCode(code, "http://localhost:5180/callback");

// token contains:
// - accessToken:  JWT, valid for 1 hour
// - refreshToken: valid for 90 days, auto-rotates
// - expiresAt:    expiration timestamp (ms)
```

<Warning>
  **Never call `exchangeCode` from the frontend.** App Secret must stay on the server. Code exchange must happen server-side.
</Warning>

## Step 6: Report Billing Events

When a user triggers a paid action in your app, report the event:

```typescript theme={null}
const result = await profy.reportEvent("generate_report", {
  token,
  metadata: { source: "web", userId: "user-123" },
});
```

The SDK automatically handles token refresh — if the Access Token has expired, it refreshes using the Refresh Token before retrying.

## Full Example

```typescript theme={null}
import { Hono } from "hono";
import { ProfyApp, type TokenData } from "@profy-ai/sdk";

const profy = new ProfyApp({
  clientId: process.env.PROFY_APP_ID!,
  clientSecret: process.env.PROFY_APP_SECRET!,
});

let tokenStore: TokenData | null = null;

const app = new Hono();

// Handle OAuth callback
app.post("/api/exchange", async (c) => {
  const { code } = await c.req.json();
  tokenStore = await profy.exchangeCode(code, "http://localhost:5180/callback");
  return c.json({ ok: true });
});

// Report billing event
app.post("/api/report", async (c) => {
  if (!tokenStore) return c.json({ error: "Not authenticated" }, 401);
  const result = await profy.reportEvent("generate_report", { token: tokenStore });
  return c.json(result);
});

export default app;
```

## Starter Template

We provide a complete full-stack starter project with Vite frontend + Hono backend:

→ [profy-app-template](https://github.com/user/profy-app-template)

```bash theme={null}
git clone https://github.com/user/profy-app-template.git
cd profy-app-template
cp .env.example .env  # Fill in App ID and App Secret
npm install && npm run dev
```

## Flow Diagram

```mermaid theme={null}
sequenceDiagram
    participant U as User
    participant A as Your App
    participant P as Profy

    U->>A: Click "Login with Profy"
    A->>P: Redirect to /oauth/authorize
    P->>U: Show consent page
    U->>P: Approve
    P->>A: Callback ?code=xxx
    A->>P: POST /oauth/token (exchange)
    P-->>A: access_token + refresh_token
    U->>A: Trigger paid action
    A->>P: POST /openapi/v1/events
    P-->>A: Credits charged
```

## Next Steps

<CardGroup cols={3}>
  <Card title="SDK Guide" icon="book" href="/zh/documentation/sdk-guide">
    Full SDK reference: dual-language support + token persistence (Contrib)
  </Card>

  <Card title="API Reference" icon="code" href="/en/api/post-token">
    Full OAuth endpoints and Events API documentation
  </Card>

  <Card title="Billing Configuration" icon="credit-card" href="/en/documentation/finance">
    Learn how to configure event pricing in Studio
  </Card>
</CardGroup>