Subscriptions and approval
API-level credentials must subscribe to the target API and be approved before they can call it. A subscription also constrains the validity period and daily call volume, and is the authorization vehicle in the API opening process.
Roles and entry points
| Role | Entry point | What they can do |
|---|---|---|
| Caller | API detail page, Account Center → Subscription Applications | Submit applications, withdraw applications under approval |
| API owner / administrator | Account Center → Approval Center | Approve, reject and terminate subscription applications |
| Subscriber | Account Center → My Subscriptions | View their own subscriptions, unsubscribe |
| API owner / administrator | Account Center → Subscription Management | View all subscriptions in the project, freeze, unfreeze, renew, unsubscribe and view call statistics |
Submitting a subscription application
Click "Subscription request" on the API detail page and fill in:
| Field | Required | Description |
|---|---|---|
| Calling credential | Yes | Select an app credential under the current account; if none exists, you are prompted to create one first |
| Subscribed API | — | Read-only; shows the API name and API ID |
| Daily call volume | No | A positive integer; leave blank for unlimited |
| Validity period | Yes | Long-term valid or custom start and end dates |
| Application reason | Yes | Up to 200 characters; describe the purpose |
Submission rules:
- A credential can have only one active or pending subscription for the same API;
- A credential with an application under approval cannot submit another one;
- Long-term validity is stored as a 100-year validity period;
- A custom validity period must have both a start date and an end date;
- If authorization already exists and expires in more than 7 days, a new application cannot be submitted;
- Permanent authorizations do not require a new application.
After submission, an in-app message is sent to the API owner.
Approval
Approvers process subscription applications in Account Center → Approval Center and can perform:
| Action | Result |
|---|---|
| Approve | Creates and activates the subscription, establishes API authorization automatically, and notifies the applicant |
| Reject | Closes the application, records the approval comments, and notifies the applicant |
| Terminate | Reclaims the authorization produced by the application; if the subscription is already active, it is unsubscribed as well |
During approval, the final quota can be adjusted based on the daily call volume in the application; leave it blank for unlimited. Only the API owner and administrators can process the corresponding applications.
Application statuses:
| Status | Meaning |
|---|---|
Under approval process | Waiting for approval; can be withdrawn |
Approved pass | Approved and the subscription has been activated |
Rejected reject | The approval was rejected |
Terminated stop | The authorization was terminated and the subscription became invalid at the same time |
Withdrawn revoke | Withdrawn by the applicant |
Subscription list and statuses
Subscription statuses:
| Status | Meaning | Can it call |
|---|---|---|
Pending pending | The subscription is created but not yet effective | No |
Active active | Normally available | Yes |
Expired expired | Past the validity period; can be flipped by a scheduled job | No |
Unsubscribed unsubscribed | Unsubscribed by the caller or approver | No |
Frozen frozen | Frozen by an administrator | No |
The subscription list shows the subscription ID, name, credential, applicant, status, validity period, daily call volume and actions.
Call quota
- The daily call volume is counted per subscription and resets at midnight every day;
- Quota is reserved atomically before the request; requests are rejected directly once the limit is reached;
- Downstream failures, client cancellations or unsuccessful responses release the reservation, so failed requests do not consume quota;
- Exceeding the quota returns HTTP 429 with the business code
40023; - A blank value means unlimited.
Freezing and unfreezing
- Only "active" subscriptions can be frozen;
- Freezing also disables the API authorization produced by the subscription; calls return business code
40021; - Only "frozen" subscriptions can be unfrozen; unfreezing restores the authorization and the remaining validity period;
- Freezing does not change the validity period and does not clear the quota already used that day.
Renewal
- Only "expired" subscriptions can be renewed;
- A new expiration date must be specified on renewal, and the daily call volume can be adjusted at the same time;
- After renewal, the status returns to "active", the authorization is re-established and the quota counter is reset;
- Renewal does not retroactively grant calling permissions for the expired period.
Unsubscription
- "Expired" or "unsubscribed" subscriptions cannot be unsubscribed again;
- Unsubscription disables the authorization immediately, and the caller can no longer access the API;
- Unsubscription cleans up the authorization projection and quota counter without affecting other credentials or other subscriptions.
Expiration and reminders
The system runs a subscription lifecycle job once per hour:
- Flips "active" subscriptions whose expiration date is earlier than today to "expired", reclaims the authorization and refreshes the runtime cache;
- Sends in-app reminders 7 days, 3 days and 1 day before expiration, only once per level;
- Sends an expiration notice after expiration, prompting renewal.
Before the scheduled job flips the status, the gateway also blocks calls based on the expiration date, so calls are not allowed during that window.
Call statistics
In subscription management you can view the call statistics of a single subscription:
- Dimensions: date, call volume, success volume, failure volume, success rate, traffic and average latency;
- Filter by environment and time range;
- Export the statistics.
The statistics use the same definition as API logs and cover only calls that pass through the gateway.
Notifications
The following events generate in-app messages:
- After a subscription application is submitted, the API owner is notified;
- After approval, rejection or termination, the applicant is notified;
- Subscription freezing, unfreezing, renewal and unsubscription;
- Graded reminders before expiration and the expiration notice.
FAQ
| Symptom | Cause | Resolution |
|---|---|---|
| The application button is unavailable | The API requires no authentication, or an application is already under approval | APIs without authentication need no application; if under approval, wait for the result |
| Message that the credential is permanently authorized | The current credential already has a permanent authorization | Call directly; no new application is needed |
| Message that the authorization is not yet in the renewal window | More than 7 days remain before expiration | Submit the application closer to expiration |
| Call returns 40021 | The subscription is frozen, expired or unsubscribed, or the API is not in the subscription scope | Check the subscription status and contact the administrator |
| Call returns 40023 | The daily call volume has reached the limit | Wait for the next-day reset or apply to adjust the quota |
| The subscription has expired but the page still shows active | The scheduled job runs once per hour | Wait for the job to run; the gateway already blocks calls based on the expiration date |