Generate keys

POST/keys

Token permission: Generate keys keys:generatespends credits

Charges the price of the chosen duration times the quantity. Without enough balance, nothing is generated or charged.

Idempotency-Key required

Every call carries the Idempotency-Key header, a unique code per request. Repeating with the same code, you get the same keys without paying again. Why?

Headers

Header	Required	Description
`Idempotency-Key`	Yes	A unique code per request (a UUID works). Up to 100 characters: letters, digits and `_ - : .`
`Content-Type`	Yes	`application/json`

Body (JSON)

Field	Type	Required	Description
`product_id`	number	Yes	The product, from the product list.
`quantity`	number	Yes	How many keys to generate, from 1 to 50.
`days`	number	No	The duration, among the product `plans`. Without it, 30 days. If the product has no 30-day plan, `days` is required.

The price is always calculated on our side, from the duration and the quantity. Any other field in the body is ignored.

Response

Field	What it is
`generation_id`	The id of this batch. It shows up in the statement as `reference_id`.
`keys[].key_code`	The key to deliver to the customer.
`keys[].user_id`	The key id in the API (to look it up and reset its HWID).
`days`	The duration of the generated keys.
`credits_spent`	The total charged.
`balance`	Your balance after the charge.

Repeating with the same Idempotency-Key and the same body, the response brings the same keys and does not charge again. It comes with "idempotent_replay": true in data and the Idempotent-Replayed: true header.

Errors

HTTP	When	What to do
`402`	Not enough balance. Nothing was generated or charged.	`errors.balance` has your balance. Buy credits and try again.
`403`	The token lacks the Generate keys permission.	Create a token with it.
`409`	The `Idempotency-Key` was already used for a different request, or the first request is still running.	New request: use a new code. Same request: wait a few seconds and retry.
`422`	Invalid data, missing or malformed `Idempotency-Key`, unavailable product, or a duration the product does not have.	The `message` says what to fix. A wrong duration lists the options in `errors.days`.
`429`	Over the limit.	Wait the seconds in `Retry-After` and try again.
`500`	Failure on our side while generating.	The credits go back to your balance (`errors.credits_refunded` says how much). Retry with the same `Idempotency-Key`. If the message mentions a partial refund, or it keeps failing, contact support.

curl -sS -X POST "$PROJECT_API_URL/keys" \
  -H "Authorization: Bearer $PROJECT_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f1c9e2a-7b4d-4c1e-9a0f-5d2b8c6e1a47" \
  -d '{"product_id":1001,"quantity":1,"days":30}'

Response · 200

{
  "success": true,
  "message": "Keys geradas.",
  "data": {
    "generation_id": 57,
    "keys": [
      { "key_code": "0a1b2c3d-4e5f6a7b-8c9d0e1f", "user_id": 204496 }
    ],
    "days": 30,
    "credits_spent": 18,
    "balance": 480
  }
}

Response · 402 — not enough balance

{
  "success": false,
  "message": "Créditos insuficientes.",
  "errors": { "balance": 12 }
}

Response · 422 — duration the product does not have

{
  "success": false,
  "message": "MOD EXEMPLO não tem key de 60 dias. Durações: 7, 15 e 30 dias.",
  "errors": { "days": [7, 15, 30] }
}

Generate keys

HeadersCopy Anchor Link

Body (JSON)Copy Anchor Link

ResponseCopy Anchor Link

Repeating the same requestCopy Anchor Link

ErrorsCopy Anchor Link

Headers

Body (JSON)

Response

Repeating the same request

Errors