App Development Guide

An App is an external application that integrates with Profy’s identity and billing system through OAuth + Events API. As an App developer, you can leverage Profy’s user system and credit-based billing to quickly monetize your product.

What Is a Profy App

Aspect	Expert	App
Runtime	Runs within the Profy platform	Self-deployed by the developer
User Interaction	Through Profy’s chat interface	Custom interface
Integration	Persona/tools/skills configuration	OAuth + API integration
Billing	METERED (per token)	METERED + PER_USE (custom events)
Distribution	Profy Expert Marketplace	Profy App Marketplace

Development Workflow

Create an App

Create a new App in Profy Studio. You will receive:

App UUID (i.e., client_id)
App Secret (i.e., client_secret, displayed only once)
OAuth configuration entry

Configure OAuth settings in your App:

Register one or more Redirect URIs (callback URLs)
Set the App’s name, description, and icon

Implement the OAuth Flow

Implement the standard OAuth 2.0 Authorization Code flow in your application:

// 1. Redirect the user to authorize
const authUrl = new URL("https://api.profy.cn/oauth/authorize");
authUrl.searchParams.set("client_id", APP_UUID);
authUrl.searchParams.set("redirect_uri", "https://your-app.com/callback");
authUrl.searchParams.set("response_type", "code");
authUrl.searchParams.set("scope", "events:write");
authUrl.searchParams.set("state", generateRandomState());
// Redirect the user to authUrl

// 2. Exchange the code for a token in the callback
const tokenResp = await fetch("https://api.profy.cn/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    grant_type: "authorization_code",
    code: callbackCode,
    redirect_uri: "https://your-app.com/callback",
    client_id: APP_UUID,
    client_secret: APP_SECRET,
  }),
});
const { access_token, refresh_token } = await tokenResp.json();

For the full flow, see OAuth Integration.

Configure Billing Meters

If your App needs per-use billing (PER_USE), configure Meters:

Add a Meter in your App settings
Define the event name (e.g., image_generation)
Set the credit price per event
Save the configuration

Meter configurations can be queried via the GET /v1/meters endpoint.

Integrate the API

Use the OAuth Token to call the Profy API:Call an AI model (METERED billing):

const resp = await fetch("https://api.profy.cn/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${access_token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "deepseek-v3",
    messages: [{ role: "user", content: userMessage }],
  }),
});

Report a custom event (PER_USE billing):

const resp = await fetch("https://api.profy.cn/v1/events", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${access_token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    event: "image_generation",
    idempotency_key: `${userId}_${taskId}`,
  }),
});

Submit for Review

Once your App is complete, submit it for review to publish on the Profy App Marketplace:

Complete the App information in Studio (name, description, icon, screenshots)
Click the “Publish” button to submit for review
The review team will check the App’s functionality and security
After approval, the App goes live on the marketplace

Publish to the Marketplace

After approval, your App will appear in the Profy App Marketplace. Users can discover, authorize, and use your App.Credit revenue earned through usage will be distributed according to the creator incentive program.

Billing Models

Apps support two billing models that can be combined:

METERED (Per-Token Billing)

Suitable for AI model invocation scenarios. When users call the Chat Completions API, credits are deducted from the user’s account based on actual token consumption.

// Credits are automatically deducted based on token usage
const resp = await fetch("https://api.profy.cn/v1/chat/completions", {
  method: "POST",
  headers: { Authorization: `Bearer ${access_token}`, ...},
  body: JSON.stringify({ model: "deepseek-v3", messages: [...] }),
});

PER_USE (Per-Event Billing)

Suitable for custom feature scenarios. Report events through the Events API, and credits are deducted at the fixed price configured in the Meter.

// Deducted at the fixed price configured in the Meter
const resp = await fetch("https://api.profy.cn/v1/events", {
  method: "POST",
  headers: { Authorization: `Bearer ${access_token}`, ...},
  body: JSON.stringify({
    event: "premium_feature",
    idempotency_key: uniqueKey,
  }),
});

App Review Process

App publishing uses a dual-track review mechanism (consistent with Expert review):

Scenario	Behavior
First publication	App enters `PENDING_REVIEW` status; goes live after approval
Version update	Old version stays online; new version enters review
Review rejected	Can be modified and resubmitted
Creator withdrawal	Pending submissions can be withdrawn

Review focus areas:

Whether the App is fully functional
Whether the OAuth flow meets security standards
Whether the user experience is reasonable
Whether billing is transparent

OAuth and App Status

The OAuth authorization flow is available as soon as the App is created, regardless of application.status. The status only controls discoverability in the marketplace:

Status	OAuth	Marketplace Visibility
`OFFLINE`	✅ Available	❌ Not visible
`PENDING_REVIEW`	✅ Available	❌ Not visible
`ONLINE`	✅ Available	✅ Visible

This means you can complete OAuth integration and testing before the App goes live.

Full Integration Example

Here is a complete App backend example built with Express + Profy SDK:

import express from "express";
import { Profy } from "@profy-ai/sdk";

const app = express();
app.use(express.json());

const APP_UUID = process.env.PROFY_APP_UUID!;
const APP_SECRET = process.env.PROFY_APP_SECRET!;

// 1. Initiate OAuth authorization
app.get("/auth/profy", (req, res) => {
  const state = crypto.randomUUID();
  // Save state to session
  const url = new URL("https://api.profy.cn/oauth/authorize");
  url.searchParams.set("client_id", APP_UUID);
  url.searchParams.set("redirect_uri", "https://your-app.com/callback");
  url.searchParams.set("response_type", "code");
  url.searchParams.set("scope", "events:write");
  url.searchParams.set("state", state);
  res.redirect(url.toString());
});

// 2. OAuth callback
app.get("/callback", async (req, res) => {
  const { code, state } = req.query;
  // Verify state

  const tokenResp = await fetch("https://api.profy.cn/oauth/token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      grant_type: "authorization_code",
      code,
      redirect_uri: "https://your-app.com/callback",
      client_id: APP_UUID,
      client_secret: APP_SECRET,
    }),
  });
  const tokens = await tokenResp.json();
  // Save tokens to database
  res.redirect("/dashboard");
});

// 3. Use OAuth Token to call API
app.post("/api/generate", async (req, res) => {
  const userToken = getUserToken(req); // Retrieve from database
  const client = new Profy({ apiKey: userToken.access_token });

  try {
    const result = await client.chat.completions.create({
      model: "deepseek-v3",
      messages: [{ role: "user", content: req.body.prompt }],
    });
    res.json({ text: result.text });
  } catch (e) {
    res.status(500).json({ error: "Generation failed" });
  }
});

app.listen(3000);

Best Practices

Store tokens securely

OAuth Tokens should be encrypted and stored in your server-side database. Do not expose them on the frontend. Use httpOnly cookies or sessions to pass user identity.

Implement automatic token refresh

Access Tokens have a 1-hour validity period. When an API call returns 401, automatically use the Refresh Token to obtain a new token, making it transparent to the user.

Use idempotency keys to prevent duplicate charges

Idempotency keys for the Events API should be uniquely tied to the business operation (e.g., {userId}_{taskId}), ensuring network retries don’t cause duplicate charges.

Display credit prices to users

Use the Meters API to retrieve feature prices and show users the credits that will be deducted before they use a paid feature. This builds trust.

Handle insufficient credits gracefully

When the Events API returns a billing failure, show users a recharge prompt instead of failing silently.

Overview

Platform API

Authentication & Keys

Integrations

SDK

Cookbook

Reference

App Development Guide

What Is a Profy App

Development Workflow

Billing Models

METERED (Per-Token Billing)

PER_USE (Per-Event Billing)

App Review Process

OAuth and App Status

Full Integration Example

Best Practices

Next Steps

OAuth Integration

Events API

​What Is a Profy App

​Development Workflow

​Billing Models

​METERED (Per-Token Billing)

​PER_USE (Per-Event Billing)

​App Review Process

​OAuth and App Status

​Full Integration Example

​Best Practices

​Next Steps

OAuth Integration

Events API

What Is a Profy App

Development Workflow

Billing Models

METERED (Per-Token Billing)

PER_USE (Per-Event Billing)

App Review Process

OAuth and App Status

Full Integration Example

Best Practices

Next Steps