API Keys

To use our Basic and Signed APIs, you need an API key

Format

RANDOM.ORG's Core API consists of two parts, the Basic API and the Signed API. If your application uses either of those, you'll need an API key, which must be included in calls to the API. An API key is a UUID generated for you by RANDOM.ORG and can look like the following:

ebfb7ff0-b2f6-41c8-bef3-4fba17be410c

If you are an application developer, you would typically create one API key for each application you make that uses RANDOM.ORG. You can monitor the performance of each key from your API Dashboard, including daily request rates and billing, and you can also start and stop your keys, create new keys, etc.

Security

Anyone that knows your API key can make requests on your behalf, which can incur billing charges to your RANDOM.ORG account. For this reason, you will most likely want to keep your API keys secret.

Hashed API Keys

One of the features of the Signed API is that it signs the responses it generates cryptographically. This allows you to prove that the random values in them really originated from RANDOM.ORG (authenticity) and that they haven't been tampered with (integrity). You'll want to be able to publish the responses, but at the same time you want to keep your API key secret, so for this reason the signed responses include a SHA-512 hash of the API key instead of the key itself. Here is an example of what a hashed API key can look like:

8hZqPJK/JU++Gem2rVOJBg8CMIu7hyx9weW+DWyQ+kALJ0fjhccGOJYzBPiny52gx9U98zFTM3dKUJGXgUOhVA==

Serial Numbers

Another feature of the Signed API is that it will attach a serial number to all your responses. Each API key has its own sequence of serial numbers. Serial numbers can be used to show that your application is not ‘cherry-picking’ amongst the random values generated, i.e., issuing repeated requests to RANDOM.ORG until it gets a particular result and only publishing that result. You can show that no cherry-picking occurs by publishing all your signed responses and showing that there are no gaps in the sequence of serial numbers associated wtih your API key.

Key Types

We may add new license tiers over time, but here is the list at present:

Identifier	License Name
beta	Beta License
developer	Developer License
commercial	Commercial (Non-Gambling) License
gambling-virtual	Virtual Item Gambling License
gambling-social	Social Gambling License
gambling-modification	Gambling Modification License
gambling-flexible	Flexible Gambling License
gambling-commercial-150	Commercial Gambling 150 License
gambling-commercial-1k	Commercial Gambling 1K License
gambling-commercial-10k	Commercial Gambling 10K License
gambling-commercial-100k	Commercial Gambling 100K License
non-profit	Non-Profit License

Daily Limits

Some types of API keys (e.g., Developer Keys) have a daily request limit and a daily bit limit. These limits depend on the license tier you chose for the API key. If your key has daily limits, these are reset every midnight UTC. Our Pricing Page shows the daily limits of the different types of API keys.

To query the limits and current usage statistics of your API key, use the getUsage method of the API. For a Developer Key, the default request limit is 1,000 requests/day and the bit limit is 250,000 bits/day.

Key States

An API key can be in one of the following states:

running

This is the normal state for an API key. It means that the key is active and can be used to serve requests, as long as those requests do not result in the key exceeding its daily request or bit limits.

stopped

If you wish to stop requests being served for a given API key, you can place it in a stopped state. While the key is stopped, any requests using that key will return an error message. The key will remain stopped until you start it again.

To query the status of your API key, use the getUsage method of the API.