Portal

Introduction

The Manager API is a set of RESTful interfaces provided by the User Portal that enables programmatic access to account management features. While the User Portal serves as a web-based management console where users can view account balances and usage statistics, the Manager API extends these capabilities by allowing users to integrate account data querying into their own systems and workflows.

Why Manager API?

The Manager API addresses several key use cases for power users and enterprise customers:

• Automated Monitoring: Integrate balance and usage statistics into internal monitoring systems for real-time alerts and dashboards
• Data Analysis: Export usage data in bulk for analysis, reporting, and business intelligence
• Cost Management: Track token consumption programmatically to optimize spending and set budget controls
• System Integration: Connect account data with existing enterprise resource planning (ERP) or billing systems

Use Cases

Use Case	Description
Real-time Balance Monitoring	Monitor account balance thresholds and trigger alerts when balance runs low
Usage Analytics	Collect and analyze token consumption patterns across different models and time periods
Cost Allocation	Track usage by token or organization for internal cost allocation and chargeback
Automated Reporting	Generate periodic usage reports for stakeholders and finance teams
Budget Control	Implement spending limits and automated notifications based on usage thresholds

API Key Statuses

Status	Description
Active	The API key is valid and can be used for authentication
Disabled	The API key is temporarily disabled and cannot be used
Revoked	The API key has been permanently revoked and cannot be restored

Creating a Management API Key

Step 1: Navigate to API Keys Section

1. Log in to your Yuansuan Portal account
2. Go to Settings or Account Management
3. Click on the Management API Keys tab

Step 2: Create New API Key

1. Click the Create API Key button
2. Fill in the required information:

Field	Description	Requirements
Name	A descriptive name for the API key	1-100 characters, required
Description	Purpose or usage context	Max 500 characters, optional
Expiration	When the key should expire	Unix timestamp or select “Never expires”
Scopes	Permission levels	Select required permissions, optional

Step 3: Configure Expiration (Optional)

Choose one of the following:

• Never expires: The key remains valid indefinitely
• Custom date: Select a specific expiration date
• Time period: Set expiration (e.g., 30 days, 90 days, 1 year)

Step 4: Save Your API Key

After clicking Create:

1. A modal will appear displaying your complete API key starting with sk_mg_
2. Copy the API key immediately - click the copy button or use Ctrl/Cmd + C
3. Store it securely in:
   • Environment variables
   • A password manager
   • A secure secrets management system
4. Click I have saved my API key to close the modal

Warning: You cannot retrieve the complete API key again after closing this window.

Viewing Your API Keys

Step 1: Access the API Keys List

1. Navigate to Settings > API Keys > Management API Keys
2. View all your API keys in a table format

Step 2: Understanding the Display

Each API key shows:

Column	Description
Name	The name you gave the API key
Display Key	Masked version (e.g., sk_mg_a1b2...5678)
Status	Current status (Active/Disabled/Revoked)
Last Used	Timestamp of last usage
Expires	Expiration date or “Never”
Created	Creation date

Step 3: Filter and Search

• Use the Status filter to show only Active, Disabled, or Revoked keys
• Use the Search box to find keys by name
• Navigate through pages using the pagination controls

Updating an API Key

Step 1: Select the API Key

1. Find the API key you want to update in the list
2. Click the Edit button (pencil icon) in the actions column

Step 2: Modify Information

You can update:

• Name: Change the display name
• Description: Update the purpose or usage notes

Note: You cannot change the API key value itself. To get a new key, create a new one and delete the old one.

Step 3: Save Changes

1. Click Save to apply changes
2. A success message will confirm the update

Deleting an API Key

Step 1: Select the API Key

1. Find the API key you want to delete
2. Click the Delete button (trash icon)

Step 2: Confirm Deletion

1. Read the warning message carefully
2. Confirm by entering the API key name
3. Click Confirm Delete

Warning: This action cannot be undone. The API key will immediately stop working.

Revoking an API Key

Step 1: Select the API Key

1. Find the API key you want to revoke
2. Click the Revoke button

Step 2: Confirm Revocation

1. Review the revocation details
2. Click Confirm Revoke

The API key status will change to Revoked and it can no longer be used.

Restoring a Revoked API Key

Step 1: Find Revoked Keys

1. Use the status filter to show Revoked keys
2. Locate the key you want to restore

Step 2: Restore the Key

1. Click the Restore button
2. Confirm the restoration action

The API key status will change back to Active.

Base URL

https://portal-api.r9s.ai/api/v1/portal/management

Authentication

All Manager API endpoints require Bearer Token authentication using a Management API Key.

Authorization: Bearer sk_mg_xxxxxxxxxxxxxxxxxx

Obtaining a Management API Key

Management API Keys can be generated through the User Portal under Settings > API Keys. Each key has specific permissions and can be revoked at any time.

Caution

Management API Keys have access to sensitive account data. Store keys securely and never expose them in client-side code or public repositories.

Available Endpoints

Endpoint	Method	Description
/balance	GET	Retrieve current account balance information
/usage	GET	Query token usage records within a specified time range

Rate Limiting

To ensure service stability and prevent abuse, the Manager API implements rate limiting:

Limit Type	Value
Rate Limit	2 requests per second
Concurrency Limit	20 concurrent requests

Best Practices for Rate Limiting

• Implement exponential backoff retry logic
• Batch requests when possible to reduce API calls
• Cache frequently accessed data locally
• Use webhooks or polling intervals appropriate to your needs

Error Handling

Common Error Codes

HTTP Status	Error Code	Description
400	invalid_request	Invalid request parameters
401	unauthorized	Authentication failed or missing
429	rate_limit_exceeded	Rate limit exceeded
500	internal_error	Server-side error

Error Response Example

{
  "meta": {
    "code": 401,
    "message": "unauthorized: invalid api key",
    "request_id": "abc123"
  },
  "data": null
}