Authentication

The Profy Platform API supports two authentication methods, each suited to different integration scenarios. All authentication information is passed via the Authorization request header.

API Key Authentication

API Key is the simplest authentication method, ideal for server-to-server direct calls.

Usage

Add Authorization: Bearer sk-pro-xxxx to the request header:

from profy import Profy

client = Profy(api_key="sk-pro-your-key-here")

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

const client = new Profy({ apiKey: "sk-pro-your-key-here" });

curl -H "Authorization: Bearer sk-pro-your-key-here" \
     https://api.profy.cn/v1/models

Characteristics

Property	Description
Prefix	`sk-pro-`
Credit Deduction	Deducted from the developer’s own account
Supported Endpoints	`/v1/agents/run`, `/v1/chat/completions`, `/v1/models`
Not Supported	`/v1/events` (requires OAuth)
Storage	Stored as SHA-256 hash; plaintext shown only at creation

Use Cases

Backend services calling AI capabilities
Automation scripts and scheduled tasks
Internal tools and management systems
Development and testing

Security Best Practices

An API Key is a credential for your account. A leak could result in credit consumption. Follow these security practices:

Do not use API Keys in frontend code — browser-side code is visible to users
Use environment variables to store keys; do not hardcode them in source code
Set expiration times — choose an expiration period when creating the key in the Platform Console
Assign scopes as needed — do not use full permissions
Rotate regularly — periodically create new keys and revoke old ones

# Recommended: Use environment variables
export PROFY_API_KEY="sk-pro-your-key-here"

import os
from profy import Profy

client = Profy(api_key=os.environ["PROFY_API_KEY"])

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

const client = new Profy({
  apiKey: process.env.PROFY_API_KEY!,
});

OAuth Bearer Authentication

OAuth authentication is suited for App scenarios that operate on behalf of users. Obtain an Access Token through the standard OAuth 2.0 Authorization Code flow.

Usage

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
     https://api.profy.cn/v1/chat/completions

Characteristics

Property	Description
Token Format	JWT (RS256 signed)
Credit Deduction	Deducted from the authorizing user’s account
Supported Endpoints	All `/v1/*` endpoints
Access Token Validity	1 hour
Refresh Token Validity	90 days (rotation mechanism)

Use Cases

Apps calling AI models on behalf of users
Third-party applications requiring user authorization
SaaS products with per-user billing
Custom billing event reporting (/v1/events supports OAuth only)

OAuth Flow Overview

User → Your App → Profy Auth Page → User Consents → Auth Code → Exchange for Token

For the detailed OAuth integration guide, see OAuth Integration.

Comparison

Dimension	API Key	OAuth Bearer
Complexity	Simple (just one key)	More complex (requires full OAuth flow)
Credit Source	Developer’s account	Authorizing user’s account
Use Case	Server-side direct calls	Apps acting on behalf of users
Events API	❌ Not supported	✅ Supported
Token Management	Manual creation and revocation	Automatic expiration and refresh
Frontend Safe	❌ Not secure	✅ Safe (short-lived tokens)

How to Choose

Determine the billing subject

If credits should be deducted from your own account → API KeyIf credits should be deducted from the user’s account → OAuth

Determine the calling pattern

If it’s a backend service calling directly → API KeyIf it’s an App acting on behalf of a user → OAuth

Determine feature requirements

If you need to use the Events API to report custom billing events → OAuthFor other scenarios, either method works

Authentication Errors

When authentication fails, the API returns the following errors:

HTTP Status	Scenario	Description
`401`	API Key invalid or expired	Check if the key is correct, revoked, or expired
`401`	Access Token expired	Use the Refresh Token to obtain a new Access Token
`401`	Refresh Token invalid	User needs to re-authorize
`403`	Insufficient permissions	The API Key’s scope does not include the requested endpoint

Error response example:

{
  "error": {
    "message": "Unauthorized",
    "type": "auth_error"
  }
}

Rate Limits

API calls are protected by rate limits. Limits are calculated per API Key or per user associated with the OAuth Token. When a rate limit is triggered, the API returns 429 Too Many Requests:

{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_error"
  }
}

You can view your API call volume and rate usage on the Usage Stats page of the Platform Console.

Overview

Platform API

Authentication & Keys

Integrations

SDK

Cookbook

Reference

Authentication

API Key Authentication

Usage

Characteristics

Use Cases

Security Best Practices

OAuth Bearer Authentication

Usage

Characteristics

Use Cases

OAuth Flow Overview

Comparison

How to Choose

Authentication Errors

Rate Limits

Next Steps

API Key Management

OAuth Integration

​API Key Authentication

​Usage

​Characteristics

​Use Cases

​Security Best Practices

​OAuth Bearer Authentication

​Usage

​Characteristics

​Use Cases

​OAuth Flow Overview

​Comparison

​How to Choose

​Authentication Errors

​Rate Limits

​Next Steps

API Key Management

OAuth Integration

API Key Authentication

Usage

Characteristics

Use Cases

Security Best Practices

OAuth Bearer Authentication

Usage

Characteristics

Use Cases

OAuth Flow Overview

Comparison

How to Choose

Authentication Errors

Rate Limits

Next Steps