Usage limited keys

Sometimes you would like to create an api key and automatically invalidate it after a certain number of uses.

Example: You are selling API access and a customer has purchased 1000 api requests from you.

Unkey allows you to set/update usage limits on individual keys and we take care of invalidating a key after it has reached its limit.

​

Example

Let’s create a new key, which can be used 100 times.

curl --request POST \
  --url https://api.unkey.dev/v1/keys.createKey \
  --header 'Authorization: Bearer <UNKEY>' \
  --header 'Content-Type: application/json' \
  --data '{
	"apiId":"<API_ID>",
	"remaining": 100
}'

Now when you verify the new key, you will receive back the remaining verifications and after all of them are used up, the key is invalid.

curl --request POST \
  --url https://api.unkey.dev/v1/keys.verifyKey \
  --header 'Content-Type: application/json' \
  --data '{
      "apiId":"<API_ID>",
      "key": "<NEW_KEY>"
	}'

{
	"valid": true,
	"remaining": 99
}

​

Custom cost

By default we deduct 1 from the remaining verifications, but in some cases you need to deduct more.

You can override this in the request body. In this example unkey would deduct 4 for every valid verification. If a key would only have 3 remaining, the request would be rejected, as there is not enough remaining left.

curl --request POST \
  --url https://api.unkey.dev/v1/keys.verifyKey \
  --header 'Content-Type: application/json' \
  --data '{
    "apiId":"<API_ID>",
    "key": "<NEW_KEY>",
    "remaining": {
      "cost": 4
    }
  }'