Keys
Renew key
Gives more days to the customer's SAME key and deducts from your balance.
POST
/keys/{user_id}/renewToken permission: Renew keys keys:renewspends credits
The customer keeps the key they already use, with more days. It charges the same price as generating a key of that duration. Without enough balance, nothing is renewed or charged.
- The days add to the current expiry. If the key has already expired, they count from now: renewing a key expired 10 days ago by 30 gives 30 days of use, not 20.
- Only an activated key can be renewed. One nobody activated still holds its duration for the activation — generate another.
- A blocked key stays blocked after the renewal.
Idempotency-Key required
As in the generation, every call carries the Idempotency-Key header. Repeating with the same code returns the same renewal without paying again. Why?
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
user_id | number | Yes | The key's user_id — it comes in the generation and in the key list. |
Headers
| Header | Required | Description |
|---|---|---|
Idempotency-Key | Yes | A unique code per renewal (a UUID works). Up to 100 characters: letters, numbers and _ - : . |
Content-Type | Yes | application/json |
Body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
days | number | Yes | How many more days, among the plans of the key's product (the product list has the durations and the price of each). |
Response
| Field | What it is |
|---|---|
renewal_id | The id of this renewal. It shows in the statement as reference_id, with type: "key_renewal". |
user_id | The renewed key. |
days | The days added. |
credits_spent | How much was charged. |
balance | Your balance after the charge. |
previous_access_end / access_end | The expiry before and after, in seconds since 1970 (Unix). |
Repeating with the same Idempotency-Key and the same body returns the same renewal, with "idempotent_replay": true and the Idempotent-Replayed: true header.
Errors
| HTTP | When | What to do |
|---|---|---|
402 | Not enough balance (or, with a credit line, over the limit). Nothing was renewed or charged. | The same fields as the generation: errors.balance, and with a credit line errors.postpaid_limit and errors.available. |
403 | The token lacks the Renew keys permission, the key is not yours, it is a recording key, or it was blocked by support (blocked_by: "support" in the list). Nothing was charged. | Create a token with the permission; recording keys and keys blocked by support are not renewed here. A key you blocked renews normally. |
404 | The key has no access in the store. | Check the user_id. |
409 | The Idempotency-Key was already used for a different request, or the first one is still running. | New request: new code. Same request: wait and retry. |
422 | Key not activated yet, activated with a mod other than the one sold, an old key that points to a store customer's account, a duration the product doesn't have (the options in errors.days), product not for sale, or missing Idempotency-Key. Nothing was charged. | The message says what to fix. Swapped mod and customer account: contact support. |
429 | Rate limit reached. See the limits. | Wait the seconds in Retry-After. |