True Random Number Service

JSON-RPC API – Release 1 – Digital Signing

These methods are intended for applications that need to support non-repudiation. The methods produce digitally signed series of true random values, generated specifically for your client. The digital signatures mean that the values can be proved to originate from RANDOM.ORG.

In the Signed API, a signature is a SHA-512 digest of the JSON representation of a random object, which has been signed with RANDOM.ORG's private key. Given a random object and its signature, anyone can verify the signature against RANDOM.ORG's public key to confirm that the numbers are authentic. To do this, the client should JSON-encode the random object, then compute the SHA-512 digest and verify the signature against it. While a client is free to use its own signature verification algorithm, it can also use the verifySignature method described here.

generateSignedIntegers

[+]

This method generates true random integers within a user-defined range. Your client must set the method property of its JSON-RPC request object to generateSignedIntegers. The request must also contain an id member, which will be returned in the response.

Required Parameters

The following parameters are mandatory and should be specified in the params array of the JSON-RPC request:

apiKey
Your API key, which is used to track the true random bit usage for your client.
n
How many random integers you need. Must be within the [1,1e4] range.
min
The lower boundary for the range from which the random numbers will be picked. Must be within the [-1e9,1e9] range.
max
The upper boundary for the range from which the random numbers will be picked. Must be within the [-1e9,1e9] range.

Optional Parameters

The following parameters are optional and can be included in the params object of your JSON-RPC request if you want functionality that is different from the default:

replacement (default value true)
Specifies whether the random numbers should be picked with replacement. The default (true) will cause the numbers to be picked with replacement, i.e., the resulting numbers may contain duplicate values (like a series of dice rolls). If you want the numbers picked to be unique (like raffle tickets drawn from a container), set this value to false.
base (default value 10)
Specifies the base that will be used to display the numbers. Values allowed are 2, 8, 10 and 16. This affects the JSON types of the resulting data as discussed below.

Successful Response

If the numbers were generated successfully, RANDOM.ORG returns a JSON-RPC response with the result property containing an object with the following named values:

random
This object encapsulates the random numbers and associated data. It is encapsulated in a separate object so it can be signed easily. The random object contains the following properties.
method
This value is copied from the request. The reason it is included in the response is to allow it to be signed by RANDOM.ORG.
hashedApiKey
A string containing a base64-encoded SHA-512 hash of the API key. This allows the client to disclose the full contents of the random object to a third party and allow that third party to associate the response with a given apiKey, without requiring the client to disclose the actual apiKey.
n, min, max, replacement, base
These values are copied from the request's params object. Values that are optional and did not appear in the request will appear in the response with the default values. The reason these are included in the response is to allow them to be signed by RANDOM.ORG.
data
An array containing the sequence of numbers requested. If the request specified base 10 (or did not specify a base and therefore defaults to 10), the elements in the array will be integers. Because JSON (according to RFC4627) only allows numbers to be written as decimal, the numbers will be typed as strings if a different base than 10 was specified in the request. Numbers in any base other than 10 will be padded with leading zeros up to the width required to display the chosen range.
completionTime
A string containing the timestamp in ISO 8601 format at which the request was completed.
serialNumber
An integer containing the serial number associated with this response. Serial numbers are allocated sequentially by RANDOM.ORG and are unique within a given apiKey (and, consequently, within the corresponding hashedApiKey).
signature
A string containing a base64-encoded signature of the random object, signed with RANDOM.ORG's private key.
bitsUsed
An integer containing the number of true random bits used to complete this request.
bitsLeft
An integer containing the (estimated) number of remaining true random bits available to the client.
requestsLeft
An integer containing the (estimated) number of remaining API requests available to the client.
advisoryDelay
An integer containing the recommended number of milliseconds that the client should delay before issuing another request.

For a successful response, the error property is absent.

A client that stores the results to show non-repudiation or implements code to satisfy other auditing requirements should store the random and signature properties, such that they can be shared publically or with auditors.

Error Response

If an error occurred, RANDOM.ORG returns a JSON-RPC response in which the result property is absent and the error property contains an error object as described in Error Codes and Messages.

Example 1

The following requests six numbers in the [1,6] range. The replacement parameter is set to true, which means the numbers will be picked with replacement, i.e., can contain duplicate values. This makes them suitable for use as dice rolls.

{
    "jsonrpc": "2.0",
    "method": "generateSignedIntegers",
    "params": {
        "apiKey": "00000000-0000-0000-0000-000000000000",
        "n": 6,
        "min": 1,
        "max": 6,
        "replacement": true,
        "base": 10
    },
    "id": 14215
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "method": "generateSignedIntegers",
            "hashedApiKey": "oT3AdLMVZKajz0pgW/8Z+t5sGZkqQSOnAi1aB8Li0tXgWf8LolrgdQ1wn9sKx1ehxhUZmhwUIpAtM8QeRbn51Q==",
            "n": 6,
            "min": 1,
            "max": 6,
            "replacement": true,
            "base": 10,
            "data": [
                2,
                4,
                4,
                1,
                5,
                3
            ],
            "completionTime": "2013-09-30 14:58:03Z",
            "serialNumber": 69260
        },
        "signature": "BxHxajeRg7Q+XGjBdFS1c7wkZbJgJlverfZ5TVDyzCKqo2K5A4pD+54EMqmysRYwkL3w2NS2DFLVrsyO1o96bW9BGp5zjjrEegz9mB+04iOTaRwmdQnLJAj/m3WRptA+qzodPCTaqud8YWBifqWCM34q98XwjX+nlahyHVHT9vf5KO0YVkD/yRI1WN5M/qX21chVvSxhWdmIrdCkrovGnysFq8SzCRNhpYx+/1P+YT2IKsH8jth9z82IAz1ANVh918H/UdpuD1dR7TD6nk3ntRgGrIiu2qqVzFi8A7/6viVgRqtffE4KVZY6O9mUJ+sGkF5Ohayms7LHSFy1VC8wMbMgwod+A8nr5yzjAC4SCUkT1bKAyWNF3SdVcLtvWdcf97Ew6RjohzCW4Vs3jUlh6jF/pj3b3++U3lBHCh43IIonw8MQ7afwpqP12yvyDym1isNjhMKYjmzWRerSvnsMyQIH8xFW7IHt2g/0qnzJgABFmUNBRKJPCD9CMgjh60sSwW7EyrGMy7/qisfE0IU74P/F7KCty/g1jIlXX5/O1lQjwY34wnoP0NXL08QteukRZZUfJQnscx1NGE+HX1c9bMBI8LC0ZFYFk+uY6ib/0rCV5OcLLE9PihCdC8WoI1x3bobr8tbtfgnXMTjogxwVXiiSN1TMnTIWlJ+KM5eSWrw=",
        "bitsUsed": 16,
        "bitsLeft": 932400,
        "requestsLeft": 199991,
        "advisoryDelay": 1000
    },
    "id": 14215
}

The method shows which part of the RANDOM.ORG API was used to generate the true random numbers. The hashedApiKey allows the client to share the full contents of the random and signature objects with third parties without disclosing its apiKey. The n, min, max and replacement parameters from the request are included too. Note that the base property has been added, even though it did not appear in the request. The data array within the result contains the true random numbers produced. The completionTime specifies UTC time zone (‘Zulu time’) by the letter ‘Z’ after the clock time. By returning the value 69,260 for serialNumber, the service indicates that this is the 69,260th request to have been completed with the apiKey in question.

The result object contains a signature of the entire random object, which allows the authenticity of the random object to be verified. Through the other fields in the result object, RANDOM.ORG also advises how many true random bits were used to satisfy the request (16) and how many bits (932,400) and requests (199,991) are left in the client's quota. It also advises the client that it can go ahead and issue the next request after a short delay (1,000 milliseconds).

Example 2

The following requests 52 numbers in the [1,52] range. The replacement parameter is set to false, meaning the numbers will be picked without replacement, i.e., duplicates will not occur. This makes them suitable to shuffle a deck of cards.

{
    "jsonrpc": "2.0",
    "method": "generateSignedIntegers",
    "params": {
        "apiKey": "00000000-0000-0000-0000-000000000000",
        "n": 52,
        "min": 1,
        "max": 52,
        "replacement": false,
        "base": 10
    },
    "id": 14215
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "method": "generateSignedIntegers",
            "hashedApiKey": "oT3AdLMVZKajz0pgW/8Z+t5sGZkqQSOnAi1aB8Li0tXgWf8LolrgdQ1wn9sKx1ehxhUZmhwUIpAtM8QeRbn51Q==",
            "n": 52,
            "min": 1,
            "max": 52,
            "replacement": false,
            "base": 10,
            "data": [
                16,
                52,
                13,
                50,
                37,
                47,
                46,
                18,
                9,
                51,
                12,
                1,
                23,
                28,
                35,
                2,
                44,
                48,
                4,
                34,
                32,
                5,
                45,
                40,
                38,
                10,
                36,
                19,
                42,
                49,
                11,
                30,
                43,
                33,
                22,
                21,
                15,
                14,
                17,
                6,
                8,
                39,
                27,
                3,
                31,
                20,
                26,
                25,
                24,
                41,
                29,
                7
            ],
            "completionTime": "2013-09-30 15:01:53Z",
            "serialNumber": 69261
        },
        "signature": "dzGPWztvKjFkH+E37L6asaWH+lISuEfdkNpEKYU3LeF32r4kgjdZmRscI0cxssAnTCNlsyr7HwpDkdE41zGa9jM4ycQoJalupuXFyvWd1/E8tH6mTI9CSLpJT8Gjrc303Z9W3rSxynx1iqniIqbfY1eglJGr819cMIhsm2fde76aiew/lxEFGoE/qjPHH7mwdPpLjAyv3S3NBQD8yPJkh+RpWJlSKsKpfPKTfFXUBkED25LQkfuVRyveg1GysNYCki2VEGlhnobOzwwX7KZskVvz7S9ze/FcfHH6anpFycO32RZb2xqnRKG2/Ob11bW7IMeBEXGdYRcgMcC98jNFVGALUoDHmi7PeGW0beuR4XSU1SGM9xLq8qaRyrkptkNX+1pruYsyJ/sVoX73UKbz7BXDMpwZZlmNzxcIpljG6NJ4ZplkHW9gOC3wV1G2wDHu0kgsveGQlWletUt0y6x7pXEcxZ+jAAxP4CEuGEuvRHeXqc1i1ozhWd2K3I9r4f95aCEGa3gAqUY6/tfoMDKBo7h2BTbdRDIv250INddkB8FWHzy6nbuKeJFtK0C5xjU+4NEuMXqMSgIXWV7uuoanVHhVFhpmslwpk0sVxATyeJDLhpU376MjDNl8dYBfwoTqv77lxK3jbMN18GHmFOUrz58vpE4dyvUstY3L/bgl6+U=",
        "bitsUsed": 296,
        "bitsLeft": 932104,
        "requestsLeft": 199990,
        "advisoryDelay": 1000
    },
    "id": 14215
}

The method, n, min, max, replacement and base parameters are the same that appeared in the request. The hashedApiKey allows the client to share the full contents of the random and signature objects with third parties without disclosing its apiKey. The random object contains the true random numbers (in the data array) produced. The service advises exactly when the request was completed and that this is the 69,261st request to have been completed with the apiKey in question.

The result object contains a signature of the entire random object, which allows the authenticity of that object to be verified. The remaining fields in the result object indicate how many true random bits were used to satisfy the request as well as how many bits and requests are left in the client's quota. The response also advises the client preferably to delay at least one second (1,000 milliseconds) before issuing a new request.

Example 3

The following requests 512 bytes, i.e., numbers in the [0,255] range. No replacement parameter is given, which means the service will use the default value of true and the numbers will be picked with replacement, i.e., duplicates are allowed. The optional base parameter is used to indicate that the client wishes the numbers to be returned in hexadecimal form. The numbers could be used as seed material for a pseudo-random number generator.

{
    "jsonrpc": "2.0",
    "method": "generateSignedIntegers",
    "params": {
        "apiKey": "00000000-0000-0000-0000-000000000000",
        "n": 512,
        "min": 0,
        "max": 255,
        "replacement": true,
        "base": 16
    },
    "id": 7249
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "method": "generateSignedIntegers",
            "hashedApiKey": "oT3AdLMVZKajz0pgW/8Z+t5sGZkqQSOnAi1aB8Li0tXgWf8LolrgdQ1wn9sKx1ehxhUZmhwUIpAtM8QeRbn51Q==",
            "n": 512,
            "min": 0,
            "max": 255,
            "replacement": true,
            "base": 16,
            "data": [
                "e8",
                "7d",
                "d6",
                "ee",
                "57",
                "e7",
                ...
            ],
            "completionTime": "2013-09-30 15:05:05Z",
            "serialNumber": 69262
        },
        "signature": "MMsM37t66JFzEkI1ZwoAr/O+N78uyfBM9hUVztSJESdfQpWUSfgp3f0j7XuxBwe7TFsJ5p7eycLGyPfHDnTdo2SiiuTQD+Ht+xMUGSTb+ZBoBy65NZrJxo1GaqIdLH7LTUfKrX0o5vk7OCUXzjMOlAYZy77Ai6JScC2L8RRBApGVNcV6Go6PnsA7JD3rAI0xrEzaZhyA7nFFfYawH0QpMoXKEAuNAtWRMkhHXQBSBc1K7i0qhMA1ZNbEh7oHhVZBgwzLAdu//TGXTHveZG1tBuBsebUgSYUj8Eb+/gfj48DfsD98LVqy3gQyIBSRoO6yWtisWLehOMK8f6R0lT7Wstep3O/N7QBknFQTxmMAxaBGgJsMHo32SrbPIHEKLadq1EyMIfPWjjjNEL2ure2bzBP/lkPDgMP1RqUSMd4Y2q5lD03uz1bRmgFE7nk3sSk2I+40WWFZIawJqtEa7tji/jlk9cAY1Vugfade/ExjgKo5zPUk3xKptpHLPhlOMFf4GLkSMUav9QH5NU1pU201CZvF7Wa7sXXnh8snY1lvsdStXFlAHAhRTSm3hHT/S+kGUkzukjqQNo7cU9Kmw4zF3rbvO6wWM1RJicphe7myh/UqZkeDc2zMegUU6y+d5ztE7lq1K4lMh7bU0axocxWwy5Q6Phpjm1cpE8Ua6a/0JPg=",
        "bitsUsed": 4096,
        "bitsLeft": 928008,
        "requestsLeft": 199989,
        "advisoryDelay": 1000
    },
    "id": 7249
}

The method, n, min, max, replacement and base parameters are the same that appeared in the request. The hashedApiKey allows the client to share the full contents of the random and signature objects with third parties without disclosing its apiKey. The random object contains the true random numbers (in the data array) produced. For brevity, only the first bytes are shown in the response. Note that the data array contains strings rather than integers, because the numbers are formatted in base 16. The service advises that this is the 69,261st request to have been completed with the apiKey in question.

The result object contains a signature of the entire random object, which allows the authenticity of the random object to be verified. The remaining fields in the result object indicate how many true random bits were used to satisfy the request as well as how many bits and requests are left in the client's quota. The service advises that the client can issue the next request without delay (0 milliseconds).

generateSignedDecimalFractions

[+]

This method generates true random decimal fractions from a uniform distribution across the [0,1] interval with a user-defined number of decimal places. Your client must set the method property of its JSON-RPC request object to generateSignedDecimalFractions. The request must also contain an id member, which will be returned in the response.

Required Parameters

The following parameters are mandatory and should be specified in the params array of the JSON-RPC request:

apiKey
Your API key, which is used to track the true random bit usage for your client.
n
How many random decimal fractions you need. Must be within the [1,1e4] range.
decimalPlaces
The number of decimal places to use. Must be within the [1,20] range.

Optional Parameters

The following parameters are optional and can be included in the params object of your JSON-RPC request if you want functionality that is different from the default:

replacement (default value true)
Specifies whether the random numbers should be picked with replacement. The default (true) will cause the numbers to be picked with replacement, i.e., the resulting numbers may contain duplicate values (like a series of dice rolls). If you want the numbers picked to be unique (like raffle tickets drawn from a container), set this value to false.

Successful Response

If the numbers were generated successfully, RANDOM.ORG returns a JSON-RPC response with the result property containing an object with the following named values:

random
This object encapsulates the random numbers and associated data. It is encapsulated in a separate object so it can be signed easily. The random object contains the following properties.
method
This value is copied from the request. The reason it is included in the response is to allow it to be signed by RANDOM.ORG.
hashedApiKey
A string containing a base64-encoded SHA-512 hash of the API key. This allows the client to disclose the full contents of the random object to a third party and allow that third party to associate the response with a given apiKey, without requiring the client to disclose the actual apiKey.
n, decimalPlaces, replacement
These values are copied from the request's params object. Values that are optional and did not appear in the request will appear in the response with the default values. The reason these are included in the response is to allow them to be signed by RANDOM.ORG.
data
An array containing the sequence of numbers requested.
completionTime
A string containing the timestamp in ISO 8601 format at which the request was completed.
serialNumber
An integer containing the serial number associated with this response. Serial numbers are allocated sequentially by RANDOM.ORG and are unique within a given apiKey (and, consequently, within the corresponding hashedApiKey).
signature
A string containing a base64-encoded signature of the random object, signed with RANDOM.ORG's private key.
bitsUsed
An integer containing the number of true random bits used to complete this request.
bitsLeft
An integer containing the (estimated) number of remaining true random bits available to the client.
requestsLeft
An integer containing the (estimated) number of remaining API requests available to the client.
advisoryDelay
An integer containing the recommended number of milliseconds that the client should delay before issuing another request.

For a successful response, the error property is absent.

A client that stores the results to show non-repudiation or implements code to satisfy other auditing requirements should store the random and signature properties, such that they can be shared publically or with auditors.

Error Response

If an error occurred, RANDOM.ORG returns a JSON-RPC response in which the result property is absent and the error property contains an error object as described in Error Codes and Messages.

Example 1

The following requests ten random decimal fractions with eight decimal places. The replacement parameter is unset, but will default to true, which means the numbers will be picked with replacement, i.e., can contain duplicate values.

{
    "jsonrpc": "2.0",
    "method": "generateSignedDecimalFractions",
    "params": {
        "apiKey": "00000000-0000-0000-0000-000000000000",
        "n": 10,
        "decimalPlaces": 8
    },
    "id": 30842
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "method": "generateSignedDecimalFractions",
            "hashedApiKey": "oT3AdLMVZKajz0pgW/8Z+t5sGZkqQSOnAi1aB8Li0tXgWf8LolrgdQ1wn9sKx1ehxhUZmhwUIpAtM8QeRbn51Q==",
            "n": 10,
            "decimalPlaces": 8,
            "replacement": true,
            "data": [
                0.95500371,
                0.65189604,
                0.10816501,
                0.74836463,
                0.55116651,
                0.6243396,
                0.1743356,
                0.60179234,
                0.26488912,
                0.42426186
            ],
            "completionTime": "2013-09-30 14:54:11Z",
            "serialNumber": 69259
        },
        "signature": "ENJ8vaXRW6OnZSSnML16OaZC4ROYAU+jFsjcVFg41Y6nAR6p9/wYde9GmV8OBgI1IkocyJbuWqTiD0y8mm/RQRNNXLXhVWwe8MuFp6CNR9N7drJMMY3/51PxmRYc9ottUFakn/JxCE2a3kwyYaD5y50WuzqTWgA1yqxRuudcWQMl4WrvIcqc8LWAqgAMUfCn/va3xQ749CzI9gpiemzbWcfEUjU56D4Kv7hJtUTN4WsVCD2TWGK5kUpmiz+R1tVfNQkgsmeFMA5J8KFAv3kVMdK09EVfCn+Y1bWEotQvkQcpepD6Lm/ZlZhriDyutv8mqSftecTVQI8VyRFilkReI0Wb7URJgS5kaYFkXwP4lVlFvvFMJCvTZ5MNZvu9boh0tYwqGQW4mZPNcaGm1BA5IShlPFz71K8SeyQAhKSxhYoK8/0zlcT0or7uJb7hcIBcErThoUqx1VzwbSLP3sr83usLhw4pqVxXQnxjV1HEVmo/csEVwM7lo6bBgN4ev0cUiBzdWzMKAv5MfjshgPyN1zUSmSkrkNgDxxhbiAkCZ6QagGTszVK0HxFG4qAhMPIwNihQNkfNalDewiodkShMWDXcbY8imqhgkfvGCXT7FdjTpmhtBHrOUInMOAEEnIurT78eNZBHDadjjwuoOogTAwXo3fLVJj5vg/ch4qGZAQ0=",
        "bitsUsed": 266,
        "bitsLeft": 932416,
        "requestsLeft": 199992,
        "advisoryDelay": 1000
    },
    "id": 30842
}

The method shows which part of the RANDOM.ORG API was used to generate the true random values. The hashedApiKey allows the client to share the full contents of the random and signature objects with third parties without disclosing its apiKey. The n and decimalPlaces parameters from the request are included too. Note that the replacement property has been added, even though it did not appear in the request. The data array within the result contains the true random values produced. Note that while eight decimal places are used, final zeroes are not shown, making some numbers appear to have fewer decimal places. Also note that the completionTime specifies UTC time zone (‘Zulu time’) by the letter ‘Z’ after the clock time. The value of the serialNumber field indicates this was the 69,259th request to be satisfied with this API key. Through the other fields in the result object, RANDOM.ORG also advises how many true random bits were used to satisfy the request (266) and how many bits (932,416) and requests (199,992) are left in the client's quota. It also advises the client that it can go ahead and issue the next request after a short delay (1,000 milliseconds).

Example 2

The following requests four decimal fractions with two decimal places. The replacement parameter is set to false, meaning the numbers will be picked without replacement, i.e., duplicates will not occur.

{
    "jsonrpc": "2.0",
    "method": "generateSignedDecimalFractions",
    "params": {
        "apiKey": "00000000-0000-0000-0000-000000000000",
        "n": 4,
        "decimalPlaces": 2,
        "replacement": false
    },
    "id": 30842
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "method": "generateSignedDecimalFractions",
            "hashedApiKey": "oT3AdLMVZKajz0pgW/8Z+t5sGZkqQSOnAi1aB8Li0tXgWf8LolrgdQ1wn9sKx1ehxhUZmhwUIpAtM8QeRbn51Q==",
            "n": 4,
            "decimalPlaces": 2,
            "replacement": false,
            "data": [
                0.43,
                0.17,
                0.18,
                0.53
            ],
            "completionTime": "2013-09-30 14:48:43Z",
            "serialNumber": 69256
        },
        "signature": "QFHrucktRS6fRyRgcBdGl1/FSwCs/Wj0bMzYpJRUC+xExvPFrlppG1XwFrMcMoP97jhEBXIWCY8weKNzlQLquaK8EEqzUehmwEYSI9B1HLOmUGuG5zO5kOC/9uHDQ/tIoIWbKVfd0diFiosYM4BxQKtQyyQT50eMvBSVn/oAIa87ZFHESxVSKziQp+5FbP+Efcmd/DRB6xVHgJ8eI31b5AnkYcIXO58NA808jPutgV1V9vmQREweSwSaAb8FVPpXQxFUqkaeIle1+FSpkX8h6bLgXxNJIrGCVl9/F7ZJN97KeV5k2dJeHBeAqi4LNfh6otukl01JYjs/paYsJDedHLvsQWd99pqrJ9GOCDnM1/+gfX3jk4rsIivbTaNSJpuWUvyzdQaZ545tmbf4XjpdWj3YviHtGiuYmT4UVN69LMYExecFH0qnRWUDx9UqiAG01Ytr6xpeH8VWMH976Cph0O+O1nz7XqE1e/rRfuYhWKeJZPWozyijWSYf8D2sg7c08HdW4yztet7b5n9EhUAd92KK08+80tagGvP8stM06cKpSfmXQEjPyCwJNqoB2bsIDO38YpYd6kpjOm+31HJ+QKNbUPQ5CvAYabcZK6CGgr3+OizMXy95DPtqLJyMmZnbg1o9CiYwGU3w5zTDAWe6/t/nMgvN/H/C1d3SPDd9Xo4=",
        "bitsUsed": 27,
        "bitsLeft": 933214,
        "requestsLeft": 199995,
        "advisoryDelay": 1000
    },
    "id": 30842
}

The method, n, decimalPlaces, and replacement parameters are the same that appeared in the request. The hashedApiKey allows the client to share the full contents of the random and signature objects with third parties without disclosing its apiKey. The random object contains the true random numbers (in the data array) produced, as well as the completion time. Note that, as in example 1, final zeroes are not shown.

The result object contains a signature of the entire random object, which allows the authenticity of that object to be verified. The remaining fields in the result object indicate how many true random bits were used to satisfy the request as well as how many bits and requests are left in the client's quota. The response also advises the client preferably to delay at least one second before issuing a new request.

Example 3

The following requests 1,000 decimal fractions with 20 decimal places. No replacement parameter is given, which means the service will use the default value of true and the numbers will be picked with replacement, i.e., duplicates are allowed.

{
    "jsonrpc": "2.0",
    "method": "generateSignedDecimalFractions",
    "params": {
        "apiKey": "00000000-0000-0000-0000-000000000000",
        "n": 1000,
        "decimalPlaces": 20
    },
    "id": 25752
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "method": "generateSignedDecimalFractions",
            "hashedApiKey": "oT3AdLMVZKajz0pgW/8Z+t5sGZkqQSOnAi1aB8Li0tXgWf8LolrgdQ1wn9sKx1ehxhUZmhwUIpAtM8QeRbn51Q==",
            "n": 1000,
            "decimalPlaces": 20,
            "replacement": true,
            "data": [
                0.88821630490575,
                0.58139253567445,
                0.22433671276792,
                0.00048544584000114,
                ...
            ],
            "completionTime": "2013-09-30 14:30:51Z",
            "serialNumber": 69254
        },
        "signature": "C+6+xeRtWmVqhs58msVJJT8fr7afx2AWRtLnhcpdGgJwy3vcweErIII4137zzfodr6lc4DKFL+Yg/ORetj+D6SDCXrNyHI+4tTAMRYkDCSsuNb1v6rjVmxnRmdbUXflKg6UWnn7bs4mF/Gs1dSlbHmM0OgEJetb9uaXrlP4IKzD+/1q8tEl9q3pRMMCpaioQv5istQNpX1si028StTHbv4/TYc7Bf5C8yfTqm4btZdJgDuW0rrLxCIHUey2Hkax/kUz0qC+BZ6rT6SU+g26VBsdyfxBiO6T+ROVAwV1qhbipt9032X/kCkHl36/QWrGBD4Ja9gg87+7eaa5Aun9EYaTd4LzDpzmBy01jUGhIyyhDj77pmUx6bWVUhdo7nVPjtA5lMTzHN3pr3Rq7gyAcab8En6x7Ebh1Hobe948F6ql+IqIsdkH4C2cNZ48iLSK63/wnOFWZOUuoTl1xb5sSmt2IWKjl45nUOiTINSwu98j77bCVDAdZgnni9rKBO+3tNdJo87pOHlwvT7OHPEya9hz0p/exOKxnrZjeSv0Zb/8+ZX/CzYvYGqve+5eEJEmoyRt8hTTk4be4N4u/BphfearQ4wF9fOtCH92Zz2FCeTqUqifqc2a9YP1xNikW5AAgwjeUBp4UgQME4RMH9o+sup8/SQzFGqM8NhQWNaOgov4=",
        "bitsUsed": 66439,
        "bitsLeft": 933268,
        "requestsLeft": 199997,
        "advisoryDelay": 1000
    },
    "id": 25752
}

The method, n and decimalPlaces parameters are the same that appeared in the request. Note that the replacement property has been added, even though it did not appear in the request. The hashedApiKey allows the client to share the full contents of the random and signature objects with third parties without disclosing its apiKey. The random object contains the random data generated by the server. For brevity, only the first four values are shown in the response. As in the previous examples, final zeroes are not shown.

The result object contains a signature of the entire random object, which allows the authenticity of the random object to be verified. The service also advises how many true random bits were used to satisfy the request and how many bits and requests are left in the client's quota. The service advises that the client can issue the next request after a short delay (1,000 milliseconds).

generateSignedGaussians

[+]

This method generates true random numbers from a Gaussian distribution (also known as a normal distribution). The form uses a Box-Muller Transform to generate the Gaussian distribution from uniformly distributed numbers. Your client must set the method property of its JSON-RPC request object to generateSignedGaussians. The request must also contain an id member, which will be returned in the response.

Required Parameters

The following parameters are mandatory and should be specified in the params array of the JSON-RPC request:

apiKey
Your API key, which is used to track the true random bit usage for your client.
n
How many random numbers you need. Must be within the [1,1e4] range.
mean
The distribution's mean. Must be within the [-1e6,1e6] range.
standardDeviation
The distribution's standard deviation. Must be within the [-1e6,1e6] range.
significantDigits
The number of significant digits to use. Must be within the [2,20] range.

Optional Parameters

There are no optional parameters. In particular, Gaussians are always picked with replacement.

Successful Response

If the numbers were generated successfully, RANDOM.ORG returns a JSON-RPC response with the result property containing an object with the following named values:

random
This object encapsulates the random numbers and associated data. It is encapsulated in a separate object so it can be signed easily. The random contains the following properties.
method
This value is copied from the request. The reason it is included in the response is to allow it to be signed by RANDOM.ORG.
hashedApiKey
A string containing a base64-encoded SHA-512 hash of the API key. This allows the client to disclose the full contents of the random object to a third party and allow that third party to associate the response with a given apiKey, without requiring the client to disclose the actual apiKey.
n, mean, standardDeviation, significantDigits
These values are copied from the request's params object. The reason these are included in the response is to allow them to be signed by RANDOM.ORG.
data
An array containing the sequence of numbers requested.
completionTime
A string containing the timestamp in ISO 8601 format at which the request was completed.
serialNumber
An integer containing the serial number associated with this response. Serial numbers are allocated sequentially by RANDOM.ORG and are unique within a given apiKey (and, consequently, within the corresponding hashedApiKey).
signature
A string containing a base64-encoded signature of the random object, signed with RANDOM.ORG's private key.
bitsUsed
An integer containing the number of true random bits used to complete this request.
bitsLeft
An integer containing the (estimated) number of remaining true random bits available to the client.
requestsLeft
An integer containing the (estimated) number of remaining API requests available to the client.
advisoryDelay
An integer containing the recommended number of milliseconds that the client should delay before issuing another request.

For a successful response, the error property is absent.

A client that stores the results to show non-repudiation or implements code to satisfy other auditing requirements should store the random and signature properties, such that they can be shared publically or with auditors.

Error Response

If an error occurred, RANDOM.ORG returns a JSON-RPC response in which the result property is absent and the error property contains an error object as described in Error Codes and Messages.

Example 1

The following requests four random numbers from a Gaussian distribution with mean 0.0 and standard deviation 1.0, accurate up to eight significant digits.

{
    "jsonrpc": "2.0",
    "method": "generateSignedGaussians",
    "params": {
        "apiKey": "00000000-0000-0000-0000-000000000000",
        "n": 4,
        "mean": 0,
        "standardDeviation": 1,
        "significantDigits": 8
    },
    "id": 42
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "method": "generateSignedGaussians",
            "hashedApiKey": "oT3AdLMVZKajz0pgW/8Z+t5sGZkqQSOnAi1aB8Li0tXgWf8LolrgdQ1wn9sKx1ehxhUZmhwUIpAtM8QeRbn51Q==",
            "n": 4,
            "mean": 0,
            "standardDeviation": 1,
            "significantDigits": 8,
            "data": [
                1.1503867,
                -0.71234425,
                1.7786077,
                0.14022009
            ],
            "completionTime": "2013-09-30 16:02:19Z",
            "serialNumber": 69263
        },
        "signature": "hM5qlrWiB5OZlo6hQ8WsrJXVl8uJOTggaXeg/6RpzdEuAObxte6a40QVC0cs8aG7/UdUE7sVtx/IIdyR8A6pomiKGzu4DXMNaBesx6OdKKlLSkzgZcHWvTSey95OOjinzO4XCxp+ZP2j+TVUSvyNy1701u7Yq1pYmhzz5h64QlKzJZob9lFdabxR8H05EdjJugb6cgDFUMiTbzqUWukJa/oyrs1Y5ZgdgC0RiT9xgFWsnaizv+SJsvhwh5bvxo1hQOtrnKZ7bxF9WBghou2VaCT2gsjmViJwrX6xOPUO2wRPsnYm+6o5cs/pZPwVkwumj7LUDm/jAvVslXbMcpOzOBvquR0uNtJT8jnF6Ev4dvOmrtjN38DRx0OmP4YDp4fj1+1Hk/jXCeXqsuTd0qdk6cFOqmyje4agjm1Qwewvl+R2rVtuoUB3FQNHd+fHbz3QmsxpL/kFRhsW7gu8Gc9w6ruc30AFUBRn+2Le9dFAHbnfsH1nP23w2AVBQONyaD5evkv0W3IuM6D9zwHCwlSkJBYfWr6AzwG0wNAkfHPRD5ZkKyEvAfl7ykqOagQVWGuXqZ3YUl1z10/c2ZTx3sMEqAqIba/SQnMkweROcIbbLOXIUWwfAJh++mVsbRvKecffTBKzodssAMvBs9/9UUsmm8/7gXNoGMDfCX1xPlKkRw8=",
        "bitsUsed": 106,
        "bitsLeft": 927902,
        "requestsLeft": 199988,
        "advisoryDelay": 1000
    },
    "id": 42
}

The method, n, mean, standardDeviation, and significantDigits parameters are the same that appeared in the request. The hashedApiKey allows the client to share the full contents of the random and signature objects with third parties without disclosing its apiKey. The data array within the result contains the true random numbers produced. Note that while eight significant digits are used, final zeroes after the decimal points are not shown, making some numbers appear to have fewer significant digits. Also note that the completionTime specifies UTC time zone (‘Zulu time’) by the letter ‘Z’ after the clock time. By returning the value 69,263 for serialNumber, the service indicates that this is the 69,263rd request to have been completed with the apiKey in question.

The result object contains a signature of the entire random object, which allows the authenticity of the random object to be verified. Through the other fields in the result object, RANDOM.ORG also advises how many true random bits were used to satisfy the request (106) and how many bits (927,902) and requests (199,988) are left in the client's quota. It also advises the client that it can go ahead and issue the next request after a short delay (1,000 milliseconds).

Example 2

The following requests 2,000 random numbers from a Gaussian distribution with mean of 1,100 and standard deviation of 100, accurate up to four decimal places. This could be used to simulate the lifetimes of lightbulbs (measured in hours), as in example 10.3.5 of Handbook of Statistical Distributions with Applications.

{
    "jsonrpc": "2.0",
    "method": "generateSignedGaussians",
    "params": {
        "apiKey": "00000000-0000-0000-0000-000000000000",
        "n": 2000,
        "mean": 1100,
        "standardDeviation": 100,
        "significantDigits": 4
    },
    "id": 42
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "method": "generateSignedGaussians",
            "hashedApiKey": "oT3AdLMVZKajz0pgW/8Z+t5sGZkqQSOnAi1aB8Li0tXgWf8LolrgdQ1wn9sKx1ehxhUZmhwUIpAtM8QeRbn51Q==",
            "n": 2000,
            "mean": 1100,
            "standardDeviation": 100,
            "significantDigits": 4,
            "data": [
                1083,
                1177,
                901.4,
                1160,
                ...
            ],
            "completionTime": "2013-09-30 16:11:18Z",
            "serialNumber": 69264
        },
        "signature": "JL8JcHFK0PHO71kKPnFQQIdq40rYN712XGwt0vevav9xVe2sroG45zyQcVfxhb6+Am2oRwyguQkDAp9D0kXWMuc1eKRW2VPA5ue7FpLkPi+gMJEx3syLvU0EalS77e+7HZL0tbJzfiI6cycPUzdMxZaf0q1EwVD06p4V80TrlzYcdSASY3O2P143ZCGdNabQSjLAyp9LNAAuzCYmAeDmH7Sq3fUpn9zJFOb7MVCo5Yikw/+0HefONYme18PcpyESWdknkRMtwcfk9Rh3hatoe+eYYmebhNMYiht7XQnO1TBivsJVDipxTz2PU0qfAEGbtS/MY72Jgh9GgTjVeTOAXyeliujnVwya8y+LBRhqAXzVgmFETymQYfokPQApJ95lpRMshsIRTGFaTFp0/ZwNpaQCXCydpVSm7aWNkaHgWCJPvqcyakGZQYyUM4CUSWtuE/P/od3JD+il3O8ikzi4qLN9YWsuanU3NRbcJVcMd76JB9iV+O/6X0075iXtsGna1OyfMQZpslbLpxbtrQwpaaYmeg60pIx2EjWP2JkKaIUseYtMf7zwpiyRfGYRgcRennGeHnbFd0jj9s/+MZDZaXo5x4JlyX9wrp+RPVf5yzChag8LE0ErX1ti6cV7lFjhtIiHK6ZRik+iXIKf+1jUwEkrd90CXJ69MOad2YgAs8I=",
        "bitsUsed": 26575,
        "bitsLeft": 901327,
        "requestsLeft": 199987,
        "advisoryDelay": 1000
    },
    "id": 42
}

The method, n, min, max, replacement and base parameters are the same that appeared in the request. The hashedApiKey allows the client to share the full contents of the random and signature objects with third parties without disclosing its apiKey. The random object contains the true random numbers (in the data array) produced, as well as the completion time. The service advises exactly when the request was completed and that this is the 69,264th request to have been completed with the apiKey in question.

The result object contains a signature of the entire random object, which allows the authenticity of that object to be verified. The remaining fields in the result object indicate how many true random bits were used to satisfy the request as well as how many bits and requests are left in the client's quota. The response also advises the client preferably to delay at least one second (1,000 milliseconds) before issuing a new request.

Example 3

The following requests 100 random numbers from a Gaussian distribution with mean 140 and standard deviation 10, accurate to six decimal places.

{
    "jsonrpc": "2.0",
    "method": "generateSignedGaussians",
    "params": {
        "apiKey": "00000000-0000-0000-0000-000000000000",
        "n": 100,
        "mean": 140,
        "standardDeviation": 10,
        "significantDigits": 6
    },
    "id": 42
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "method": "generateSignedGaussians",
            "hashedApiKey": "oT3AdLMVZKajz0pgW/8Z+t5sGZkqQSOnAi1aB8Li0tXgWf8LolrgdQ1wn9sKx1ehxhUZmhwUIpAtM8QeRbn51Q==",
            "n": 100,
            "mean": 140,
            "standardDeviation": 10,
            "significantDigits": 6,
            "data": [
                122.341,
                127.849,
                145.893,
                165.021,
                ...
            ],
            "completionTime": "2013-09-30 16:16:09Z",
            "serialNumber": 69265
        },
        "signature": "SaKCTsQhmDLBKBvN0RAkMh0gSDXTqk6QS0iiTGyPcrtz48gGFiS2McSa3eAn+d1uw3B4Pno4Xtrc2Swo/XuXfk4QGRlHhcxkru5qMBxnX83tnTda7mJn7f/vUKQWPtrTzeldl36TYlM/++QB9p7OpgI5yTnDE9yjc9CytUQwa5I3/9bXwXRMNsI6puQANfrYqUHqewCqLf5T1Yfvbca7w6Gurkq8cHHMuPCQvXhwKA6KqaV4EiiW1uoR4ZrEDNkdImWCz8IwpBtMqGpT3gw9p8ms7l29ntYKe3QjUTAtMuTvZY39nTKmr2Yds4DDrNMrSm98zjjCp1CD5gEiI2rrb9ZrNRkmLFQ5cXrGTpoYvfenkcTcbmDulWoaFnrxpHSOpk2r8Pukz6Mb/l+/mIsBdOFxrJIP5jmPbSQN+q3mQD9nrUt4k2xnEAiPhHhtJyMdGmrF0EjVCtjKMaH2Xu4H+uQQsOpZf3lxSsbElCNaghSyrbsgO5F6YG+/tg4Uuhl/uksGOgup0OUsbIDAGZC1GH+eVACvchhHsfHpugF8Pdak445owi6ifFnWcfCiL6muVUszkjC7hXNwl605qmxnEjbafalb3tsfsbscyU/pPF00/HID3IZ2ebkTPYIYodB5JNtYlQO/wwgzvgI+7IIBfGYKzMIeX4CRfcWDjY5ju6A=",
        "bitsUsed": 1993,
        "bitsLeft": 899334,
        "requestsLeft": 199986,
        "advisoryDelay": 1000
    },
    "id": 42
}

The method, n, mean, standardDeviation, and significantDigits parameters are the same that appeared in the request. The hashedApiKey allows the client to share the full contents of the random and signature objects with third parties without disclosing its apiKey. The random object contains the random data generated by the server. For brevity, only the first four values are shown in the response. As in example 1, final zeroes after the decimal point are not shown. The service advises that this is the 69,265th request to have been completed with the apiKey in question.

The result object contains a signature of the entire random object, which allows the authenticity of the random object to be verified. The remaining fields in the result object indicate how many true random bits were used to satisfy the request as well as how many bits and requests are left in the client's quota. The service advises that the client can issue the next request after a short delay (1,000 milliseconds).

generateSignedStrings

[+]

This method generates true random strings. Your client must set the method property of its JSON-RPC request object to generateSignedStrings. The request must also contain an id member, which will be returned in the response.

Required Parameters

The following parameters are mandatory and should be specified in the params array of the JSON-RPC request:

apiKey
Your API key, which is used to track the true random bit usage for your client.
n
How many random strings you need. Must be within the [1,1e4] range.
length
The length of each string. Must be within the [1,20] range. All strings will be of the same length
characters
A string that contains the set of characters that are allowed to occur in the random strings. The maximum number of characters is 80.

Optional Parameters

The following parameters are optional and can be included in the params object of your JSON-RPC request if you want functionality that is different from the default:

replacement (default value true)
Specifies whether the random strings should be picked with replacement. The default (true) will cause the strings to be picked with replacement, i.e., the resulting list of strings may contain duplicates (like a series of dice rolls). If you want the strings to be unique (like raffle tickets drawn from a container), set this value to false.

Successful Response

If the strings were generated successfully, RANDOM.ORG returns a JSON-RPC response with the result property containing an object with the following named values:

random
This object encapsulates the random numbers and associated data. It is encapsulated in a separate object so it can be signed easily. The random object contains the following properties.
method
This value is copied from the request. The reason it is included in the response is to allow it to be signed by RANDOM.ORG.
hashedApiKey
A string containing a base64-encoded SHA-512 hash of the API key. This allows the client to disclose the full contents of the random object to a third party and allow that third party to associate the response with a given apiKey, without requiring the client to disclose the actual apiKey.
n, length, characters, replacement
These values are copied from the request's params object. Values that are optional and did not appear in the request will appear in the response with the default values. The reason these are included in the response is to allow them to be signed by RANDOM.ORG.
data
An array containing the strings requested.
completionTime
A string containing the timestamp in ISO 8601 format at which the request was completed.
serialNumber
An integer containing the serial number associated with this response. Serial numbers are allocated sequentially by RANDOM.ORG and are unique within a given apiKey (and, consequently, within the corresponding hashedApiKey).
signature
A string containing a base64-encoded signature of the random object, signed with RANDOM.ORG's private key.
bitsUsed
An integer containing the number of true random bits used to complete this request.
bitsLeft
An integer containing the (estimated) number of remaining true random bits available to the client.
requestsLeft
An integer containing the (estimated) number of remaining API requests available to the client.
advisoryDelay
An integer containing the recommended number of milliseconds that the client should delay before issuing another request.

For a successful response, the error property is absent.

A client that stores the results to show non-repudiation or implements code to satisfy other auditing requirements should store the random and signature properties, such that they can be shared publically or with auditors.

Error Response

If an error occurred, RANDOM.ORG returns a JSON-RPC response in which the result property is absent and the error property contains an error object as described in Error Codes and Messages.

Example 1

The following requests eight strings of ten characters in length. Only lowercase characters from the English alphabet are allowed. The replacement parameter is set to true, which means the strings will be picked with replacement, i.e., can contain duplicate values.

{
    "jsonrpc": "2.0",
    "method": "generateSignedStrings",
    "params": {
        "apiKey": "00000000-0000-0000-0000-000000000000",
        "n": 8,
        "length": 10,
        "characters": "abcdefghijklmnopqrstuvwxyz",
        "replacement": true
    },
    "id": 42
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "method": "generateSignedStrings",
            "hashedApiKey": "oT3AdLMVZKajz0pgW/8Z+t5sGZkqQSOnAi1aB8Li0tXgWf8LolrgdQ1wn9sKx1ehxhUZmhwUIpAtM8QeRbn51Q==",
            "n": 8,
            "length": 10,
            "characters": "abcdefghijklmnopqrstuvwxyz",
            "replacement": true,
            "data": [
                "vnbbvnytjx",
                "wazkxrindd",
                "bdkyzpwggk",
                "veanpfbyun",
                "dbeswfjiak",
                "gfgmrppopl",
                "chwkiiwozg",
                "xvdfnqdqdw"
            ],
            "completionTime": "2013-09-30 16:56:46Z",
            "serialNumber": 69266
        },
        "signature": "XFGHFilFS5jNvL8jmlvzvBogF8SQqFTGkeIUzs4NzzKGe4Qy7R8Uhl0Oi/gBuxBGIL94IjfXmPaEWD4gycuxOv+Yg5GEKlSVyeXY0D1AJF6E6e5HEhpCp0leo+rEQi2uR8tM21BVrGbAq9mWuJy8pkBa4CxQcvkyu2+4ct9Ci1PMTyr+ia+yo46rzW1s8cHXtIHUL4BOC6JZWahzknR+zzdY2sBQ2D+7FZkXo9J34HLtnoXmFkXMFU/yIGfUnfeEKlqBtNFk11C6JkWULX7cBdfMxOGaEyu+StRYnhjjixIxQvbJgPUG7T9L1+e/rP/iTYvuEZUViRhiJxLKkB85mlPSZYkclgZjV/90d0SR+ZciVJwkGdHvM+5vyN3XzoDAhZpDmAr3sp5uDD1oOA4KEKqqnZYiTQaHgVauWi9cXsGznoEZFB6AUtEWz5z+kvAayKwNP1//2Ob3KcELNZDOVgoo3uEJW1QjwyonmWoO2gVKC2vwcgyLnMDme21Nh8q+yRusSCveCOCVr3zWInW0K6Oy8CpvfpS5HReN5q7eYbN/mIKrdgYDro04jtjNCDVTx/+WzZEVbnN6Egi+3RpyPhI6t48//9sE9LELhnjf+D++JOo8Z52KckfXRHu+UFkBvvrEwyM68ivbkZiJMJYme4ZPt6UVFmv6yHy1O15bkNo=",
        "bitsUsed": 376,
        "bitsLeft": 898958,
        "requestsLeft": 199985,
        "advisoryDelay": 1000
    },
    "id": 42
}

The method shows which part of the RANDOM.ORG API was used to generate the true random numbers. The hashedApiKey allows the client to share the full contents of the random and signature objects with third parties without disclosing its apiKey. The n, length, characters and replacement parameters from the request are included too. The data array within the result contains the true random strings produced. The completionTime specifies UTC time zone (‘Zulu time’) by the letter ‘Z’ after the clock time. By returning the value 69,266 for serialNumber, the service indicates that this is the 69,266th request to have been completed with the apiKey in question.

The result object contains a signature of the entire random object, which allows the authenticity of the random object to be verified. Through the other fields in the result object, RANDOM.ORG also advises how many true random bits were used to satisfy the request (376) and how many bits (898,958) and requests (199,985) are left in the client's quota. It also advises the client that it can go ahead and issue the next request after a short delay (1,000 milliseconds).

Example 2

The following requests ten strings of length eight. Allowable characters are all letters from the English alphabet (uppercase and lowercase letters are treated as separate characters) as well as decimal digits and a few special characters. The replacement parameter is set to false, meaning that strings will be generated without replacement, such that there will be no duplicates amongst them.

{
    "jsonrpc": "2.0",
    "method": "generateSignedStrings",
    "params": {
        "apiKey": "00000000-0000-0000-0000-000000000000",
        "n": 10,
        "length": 8,
        "characters": "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!#$%&*",
        "replacement": false
    },
    "id": 42
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "method": "generateSignedStrings",
            "hashedApiKey": "oT3AdLMVZKajz0pgW/8Z+t5sGZkqQSOnAi1aB8Li0tXgWf8LolrgdQ1wn9sKx1ehxhUZmhwUIpAtM8QeRbn51Q==",
            "n": 10,
            "length": 8,
            "characters": "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!#$%&*",
            "replacement": false,
            "data": [
                "DGrnXCnK",
                "jwDaYy34",
                "t#*&HEaP",
                "j*q7hk#w",
                "V*2WstqU",
                "oU8gVte*",
                "U0RZ3onl",
                "4f9#2#an",
                "NBI2u9YO",
                "WpLBViPr"
            ],
            "completionTime": "2013-09-30 17:03:21Z",
            "serialNumber": 69267
        },
        "signature": "DmGcm6TPaWbWA8f6eeSMOpVvYwnTY7IpUNrft72nV3yNs+yN9dqBRUHei0PhsSnhdzBgE5dHfRcKhg0QovDRBnohO0uxm/4C5YvsK4CWuygwbi3nqMYCcyKoraopYQX1cS07ciWsbviwjSg1LsVeQ9WrCDI4IRJYnFAgperzgdhqpbb0uVgfuvNzElHw+OSK9KpwO6jUhaT66iMr2O8mX0uIi8poEL0pYbc5PwTlzCLuqM9dhSIyJXEsNuIHxmlj++UXgN5g/7l37na/dbmSUavMxTpK0vY1tqJsXMQvsVWvAh1AD0jrhGCkTHtT/u9LAYZ3bLWbEeXvxLzChQ/wjoQxYE/gd+GcA7PAAa8IOgNEhr0AUnLCgzpLblcpmw2fkoorgYO2RbaJj3S835sYrTndp1kid3wGcVmRcWwHGbsRO5dq1GyST8S/x+iJh65sQZbm0kZKQVfzEYFuoo86XsiX6w9e4x9UqHQlY39FFYTIGtGQv3zAuNla6LHcIvmxfBChemay7rT+wDzZzV5lK4Tg6OEY7syCPvnu4quQhohDAtGAihEl8fp32XbaKkBS9kRhQotuF8DjNqHrXgGeDhId/cn7l/Z56WEMupMxTaBSYMVN12g/DLX/F8nd5Dk7rPHGEBNuPvAPTgB9O/D5or0cwXv8oQnIS1jHNvKXYxk=",
        "bitsUsed": 487,
        "bitsLeft": 898471,
        "requestsLeft": 199984,
        "advisoryDelay": 1000
    },
    "id": 42
}

The method, n, min, max, replacement and base parameters are the same that appeared in the request. The hashedApiKey allows the client to share the full contents of the random and signature objects with third parties without disclosing its apiKey. The random object contains the true random strings (in the data array) produced. The service advises that this is the 69,267th request to have been completed with the apiKey in question.

The result object contains a signature of the entire random object, which allows the authenticity of the random object to be verified. The remaining fields in the result object indicate how many true random bits were used to satisfy the request as well as how many bits and requests are left in the client's quota. The response also advises the client preferably to delay at least one second (1,000 milliseconds) before issuing a new request.

Example 3

The following requests sixteen strings of length four. All characters from the Danish and Norwegian alphabet are allowed. The replacement parameter is given, which means the service will use the default value of true and the strings will be picked with replacement, i.e., duplicates are allowed.

{
    "jsonrpc": "2.0",
    "method": "generateSignedStrings",
    "params": {
        "apiKey": "00000000-0000-0000-0000-000000000000",
        "n": 16,
        "length": 4,
        "characters": "abcdefghijklmnopqrstuvwxyzæøåABCDEFGHIJKLMNOPQRSTUVWXYZÆØÅ"
    },
    "id": 4352
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "method": "generateSignedStrings",
            "hashedApiKey": "oT3AdLMVZKajz0pgW/8Z+t5sGZkqQSOnAi1aB8Li0tXgWf8LolrgdQ1wn9sKx1ehxhUZmhwUIpAtM8QeRbn51Q==",
            "n": 16,
            "length": 4,
            "characters": "abcdefghijklmnopqrstuvwxyzæøåABCDEFGHIJKLMNOPQRSTUVWXYZÆØÅ",
            "replacement": true,
            "data": [
                "PQXD",
                "Fwsx",
                "miHØ",
                "ptez",
                "TXØP",
                "QFØY",
                "MERÆ",
                "Jæøk",
                "fØhw",
                "GQik",
                "JNIz",
                "wNåi",
                "kIqi",
                "ØTLw",
                "KrWI",
                "JØmy"
            ],
            "completionTime": "2013-09-30 17:08:55Z",
            "serialNumber": 69268
        },
        "signature": "kVBWHv6McfThQl2MZDrkItlY9aU28qC1//c9kZHX1OoPKWWxXfKmSOBDald8VIrN69luZz3/cT+x3cApIc7AGSQdv0AVesuALFmnvhdR/CnD4A+pmUPIMyxfGnHAV377xrB3OkOHlMhGtvh1mOHc/2Rp7i9wRr9+dz0xSarz8QKms5N9qLfNuXt/Kmu/QcIeq+buIIPAlaJSZj3PXWisr633p4kk76qXMFuBt7Kby+oJt8qhSlOhhMC8VXGTYhm38t4cPVEAnxxjzXZegQ3xOc0QOG41F18hwxj96LtpYk07fn3bjzrpjxv8qe/ppw5FhRf1C+wAcTZwoMLptG/YQbVz+KC3MfNlvLBQ0u7Mn6gRhohnH9fQHBNOw1Hvp6GEcKjiPBcBf+rUXXkePSTYkU5Bmuxu5JWYD7T32VkAd6CuM7brX5+Y/870lUSIPgNVA2w0iamHs4D0rRy4yCSXuLRe+aWatAI64CQWwezREIYHiWodGGfNgK9t3XBZRUbLJji5XPZOMaWi+Exc5fpzRz0/rtUnLshmeuLwyZ9afDVCWIXVfwsYdUkwrczSp323lmt8acVlDnVzY0o8nPqMflCl/hwul93S2i6RnulqkyoBbkNvjKMD1rhJAll8mb5h/WRjecslhgovqsmOAFoATpPwkiNQR8eiKU3GEGsA11c=",
        "bitsUsed": 375,
        "bitsLeft": 898096,
        "requestsLeft": 199983,
        "advisoryDelay": 1000
    },
    "id": 4352
}

The method, n, length, characters and replacement parameters are the same that appeared in the request. The hashedApiKey allows the client to share the full contents of the random and signature objects with third parties without disclosing its apiKey. The random object contains the random data generated by the server. The service advises that this is the 69,268th request to have been completed with the apiKey in question.

The result object contains a signature of the entire random object, which allows the authenticity of the random object to be verified. The remaining fields in the result object indicate how many true random bits were used to satisfy the request as well as how many bits and requests are left in the client's quota. The service advises that the client can issue the next request after a short delay (1,000 milliseconds).

generateSignedUUIDs

[+]

This method generates version 4 true random Universally Unique IDentifiers (UUIDs) in accordance with section 4.4 of RFC 4122. Your client must set the method property of its JSON-RPC request object to generateSignedUUIDs. The request must also contain an id member, which will be returned in the response.

Required Parameters

The following parameters are mandatory and should be specified in the params array of the JSON-RPC request:

apiKey
Your API key, which is used to track the true random bit usage for your client.
n
How many random UUIDs you need. Must be within the [1,1e3] range.

Optional Parameters

This method has no optional parameters.

Successful Response

If the UUIDs were generated successfully, RANDOM.ORG returns a JSON-RPC response with the result property containing an object with the following named values:

random
This object encapsulates the random UUIDs and associated data. It is encapsulated in a separate object so it can be signed easily. The random object contains the following properties.
method
This value is copied from the request. The reason it is included in the response is to allow it to be signed by RANDOM.ORG.
hashedApiKey
A string containing a base64-encoded SHA-512 hash of the API key. This allows the client to disclose the full contents of the random object to a third party and allow that third party to associate the response with a given apiKey, without requiring the client to disclose the actual apiKey.
n
This value is copied from the request's params object. The reason it is included in the response is to allow it to be signed by RANDOM.ORG.
data
An array containing the sequence of UUIDs requested, represented as strings.
completionTime
A string containing the timestamp in ISO 8601 format at which the request was completed.
serialNumber
An integer containing the serial number associated with this response. Serial numbers are allocated sequentially by RANDOM.ORG and are unique within a given apiKey (and, consequently, within the corresponding hashedApiKey).
signature
A string containing a base64-encoded signature of the random object, signed with RANDOM.ORG's private key.
bitsUsed
An integer containing the number of true random bits used to complete this request.
bitsLeft
An integer containing the (estimated) number of remaining true random bits available to the client.
requestsLeft
An integer containing the (estimated) number of remaining API requests available to the client.
advisoryDelay
An integer containing the recommended number of milliseconds that the client should delay before issuing another request.

For a successful response, the error property is absent.

A client that stores the results to show non-repudiation or implements code to satisfy other auditing requirements should store the random and signature properties, such that they can be shared publically or with auditors.

Error Response

If an error occurred, RANDOM.ORG returns a JSON-RPC response in which the result property is absent and the error property contains an error object as described in Error Codes and Messages.

Example 1

The following requests a single UUID.

{
    "jsonrpc": "2.0",
    "method": "generateSignedUUIDs",
    "params": {
        "apiKey": "00000000-0000-0000-0000-000000000000",
        "n": 1
    },
    "id": 15998
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "method": "generateSignedUUIDs",
            "hashedApiKey": "oT3AdLMVZKajz0pgW/8Z+t5sGZkqQSOnAi1aB8Li0tXgWf8LolrgdQ1wn9sKx1ehxhUZmhwUIpAtM8QeRbn51Q==",
            "n": 1,
            "data": [
                "9f7bc2c6-9673-4c0a-aef4-aa6dd9d62ec8"
            ],
            "completionTime": "2013-09-30 17:24:33Z",
            "serialNumber": 69269
        },
        "signature": "FvhPYF3jd+KLk6vxrvDIPU9xrkDhjv/WMOWbmBhKjYG6+vxGYFBY0s68DXHirF6mWpbaXLv27fw7GK32pzbUR7SmSDT9xmdwqedVMJzDXoX06MSh000k5j6gK2xV/1o84FxxLpsmOeOLCRQy0CeHax21E7SptJn90PLl3a1xu08b7FOU60AbktrQiBG3nxsCmLjfiBJ8qACowGcG34pq8FE1NYijnZO4h9q2TxySeHFPlJ69dnOUbXuWUniGxHctOqNY4cRrNo808Z61MuqgPteX62MtR9xslhLC107jc/yOYUiTVblTihABsfWPvGbt8+S7b9M92jn5vxN7eNUx1duEBtaKnV0MX/ycm2D4lqqxQ4cYuB8h7NCwJwFnC5M/n4QDVcNGN7I7uXyHtl+7kU4nThZ7g6PVSiEV1dVRusc2AdO+KEGukRZMz8QjD1SAEchf9URUp/TLJID75JcykzBckLkOwpI4DnVodgKhdetFc3HEQ7BxM6FOyb7xuuzrq4BAMEqS2kvAo4SGHafk/8eilCCNkC3jfdWdHMikz1VZxJ6ykjdvjM2sMhfxSN+kNW93RuYtL0tDkkiTbfAw06vuIFTiHgKtiWpNYbVyZcAeVibTzmy6cyG29aYIj3Yyh1fRCuJPx1Js/ZW6vhRGFisSdF5Cakcw4EAzTdhDPxU=",
        "bitsUsed": 122,
        "bitsLeft": 897974,
        "requestsLeft": 199982,
        "advisoryDelay": 1000
    },
    "id": 15998
}

The method and n parameters are the same that appeared in the request. The hashedApiKey allows the client to share the full contents of the random and signature objects with third parties without disclosing its apiKey. The data array within the result contains the UUID produced. Note that the completionTime specifies UTC time zone (‘Zulu time’) by the letter ‘Z’ after the clock time. By returning the value 69,263 for serialNumber, the service indicates that this is the 69,263rd request to have been completed with the apiKey in question.

The result object contains a signature of the entire random object, which allows the authenticity of the random object to be verified. Through the other fields in the result object, RANDOM.ORG also advises how many true random bits were used to satisfy the request (122) and how many bits (897,974) and requests (199,982) are left in the client's quota. It also advises the client that it can go ahead and issue the next request after a short delay (1 second).

Example 2

The following requests eight UUIDs.

{
    "jsonrpc": "2.0",
    "method": "generateSignedUUIDs",
    "params": {
        "apiKey": "00000000-0000-0000-0000-000000000000",
        "n": 8
    },
    "id": 16135
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "method": "generateSignedUUIDs",
            "hashedApiKey": "oT3AdLMVZKajz0pgW/8Z+t5sGZkqQSOnAi1aB8Li0tXgWf8LolrgdQ1wn9sKx1ehxhUZmhwUIpAtM8QeRbn51Q==",
            "n": 8,
            "data": [
                "86a2814d-0eb2-4916-a2c6-77a3de219827",
                "f800cbaa-6735-4b73-bb1a-ec73ae311ed7",
                "c26c1173-240a-49b8-96e4-9dde86b2b939",
                "335b0061-c323-4df3-93ce-b4a4c37bc066",
                "d5ad5cee-2ad8-4ab1-841a-035fde6896cc",
                "faed82a8-200b-42f1-a391-3e2c3aec1291",
                "404844db-bfb4-4291-9da3-7abf591d7d67",
                "8939a377-a7a9-4b11-98a9-0546db7c3c05"
            ],
            "completionTime": "2013-09-30 17:29:01Z",
            "serialNumber": 69270
        },
        "signature": "DEVcBMCCOQUAxhsH9zsI21JzbaAdTfcThC+2wV8VS1x9JmSzUk9GGGV8gGhqGMfyIK2EmLEDrObs7ukSgjuyQP+rOQARwvWtsQEWrdkYYyTwj9YS9QBwmjMHq4ntrdqvozb+jpxtbbeITOKRgVFyLqQq1ZU4zUec7YXrOq7ye4ZrdrBGmSREQ7azagx9M4YYFBXCAFhmMYtQXvzpCr174AKoPiiK9gz4lL5IdScyQABx/2stEvX11OFelOFvsMZ7Njy3Rw6774hVOXZIiE8Caichad+W9W3x88FkRbf9C/ZMFXtnbDw+Z+7rsO2LajZDQdhQlBFDDDars3JZtx+wraQiW4qAz4jO8v+7eH3/WPqll+aYa6SNUAGvSp3asAjoonpJyHbzVzQA6w+Hz3l9zWBJAXbqQTku6yL3xbXjwF+ap/8XYzX9nO4/GXugCrt+Moc4oFEhHq2nffdfHanNXH3NOdb8KlCJHxTkJP699r2e3JfYJb2J5h9gGr+DuCrfrrN5OPfdzCqkkvBbIwMG3WVcBLVOz154IKdzsAKr3/0h/2thj0PsQTqOCqNIhKRef5sp6RbZiPdG6VsS+caG0IoIvnegcaMzS+qCiwyY4fdcVgkqEBMpO56mLjDqaIbDpfIemVZpnXHZSx41FjEtEW7s6NO/VR4IUzPcUh7Z8+A=",
        "bitsUsed": 976,
        "bitsLeft": 896998,
        "requestsLeft": 199981,
        "advisoryDelay": 1000
    },
    "id": 16135
}

The method and n parameters are the same that appeared in the request. The hashedApiKey allows the client to share the full contents of the random and signature objects with third parties without disclosing its apiKey. The random object contains the true random UUIDs (in the data array) produced, as well as the completion time. The service advises exactly when the request was completed and that this is the 69,270th request to have been completed with the apiKey in question.

The result object contains a signature of the entire random object, which allows the authenticity of that object to be verified. The remaining fields in the result object indicate how many true random bits were used to satisfy the request as well as how many bits and requests are left in the client's quota. The response also advises the client can go ahead and issue the next request after a delay of 1 second (1,000 milliseconds).

generateSignedBlobs

[+]

This method generates Binary Large OBjects (BLOBs) containing true random data. Your client must set the method property of its JSON-RPC request object to generateSignedBlobs. The request must also contain an id member, which will be returned in the response.

Required Parameters

The following parameters are mandatory and should be specified in the params array of the JSON-RPC request:

apiKey
Your API key, which is used to track the true random bit usage for your client.
n
How many random blobs you need. Must be within the [1,100] range.
size
The size of each blob, measured in bits. Must be within the [1,1048576] range and must be divisible by 8.

The total size of all blobs requested must not exceed 1,048,576 bits (128 KiB).

Optional Parameters

The following parameters are optional and can be included in the params object of your JSON-RPC request if you want functionality that is different from the default:

format (default value base64)
Specifies the format in which the blobs will be returned. Values allowed are base64 and hex.

Successful Response

If the blobs were generated successfully, RANDOM.ORG returns a JSON-RPC response with the result property containing an object with the following named values:

random
This object encapsulates the random blobs and associated data. It is encapsulated in a separate object so it can be signed easily. The random object contains the following properties.
method
This value is copied from the request. The reason it is included in the response is to allow it to be signed by RANDOM.ORG.
hashedApiKey
A string containing a base64-encoded SHA-512 hash of the API key. This allows the client to disclose the full contents of the random object to a third party and allow that third party to associate the response with a given apiKey, without requiring the client to disclose the actual apiKey.
n, size, format
These values are copied from the request's params object. Values that are optional and did not appear in the request will appear in the response with the default values. The reason these are included in the response is to allow them to be signed by RANDOM.ORG.
data
An array containing the blobs requested. Each blob will be formatted as a string encoded in the format specified in the request.
completionTime
A string containing the timestamp in ISO 8601 format at which the request was completed.
serialNumber
An integer containing the serial number associated with this response. Serial numbers are allocated sequentially by RANDOM.ORG and are unique within a given apiKey (and, consequently, within the corresponding hashedApiKey).
signature
A string containing a base64-encoded signature of the random object, signed with RANDOM.ORG's private key.
bitsUsed
An integer containing the number of true random bits used to complete this request.
bitsLeft
An integer containing the (estimated) number of remaining true random bits available to the client.
requestsLeft
An integer containing the (estimated) number of remaining API requests available to the client.
advisoryDelay
An integer containing the recommended number of milliseconds that the client should delay before issuing another request.

For a successful response, the error property is absent.

A client that stores the results to show non-repudiation or implements code to satisfy other auditing requirements should store the random and signature properties, such that they can be shared publically or with auditors.

Error Response

If an error occurred, RANDOM.ORG returns a JSON-RPC response in which the result property is absent and the error property contains an error object as described in Error Codes and Messages.

Example 1

The following requests a single blob containing 1,024 true random bits (128 bytes), for example to seed a pseudo-random number generator.

{
    "jsonrpc": "2.0",
    "method": "generateSignedBlobs",
    "params": {
        "apiKey": "00000000-0000-0000-0000-000000000000",
        "n": 1,
        "size": 1024
    },
    "id": 26066
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "method": "generateSignedBlobs",
            "hashedApiKey": "oT3AdLMVZKajz0pgW/8Z+t5sGZkqQSOnAi1aB8Li0tXgWf8LolrgdQ1wn9sKx1ehxhUZmhwUIpAtM8QeRbn51Q==",
            "n": 1,
            "size": 1024,
            "format": "base64",
            "data": [
                "KchEoBw5W2J4l7UARgR2Ku6sTkiudQbHs/0hocw/8RahUaslx4EAHNZMoeN5P7jIakx+UFnLfuyjbijVySzoz/Ar1QC52rBQxTo3Ya+m3dCWpLmkN355UnD6nBbtieHlBd2qBUszXebneulhDJNrVuNBeX7qwpTwsXO+kD/Zxxc="
            ],
            "completionTime": "2013-09-30 17:42:32Z",
            "serialNumber": 69271
        },
        "signature": "RP+b5vmSpQJK37t5BbVyJSxHB1qvv2eMQEZBNSWG2bH0j3etSNpi+LDw5af6pDDunomBcUhirQn0+utH11WXbrTnl8UhnKoNzHzU5fhpBTCFwf42Tenlp9bsrAMIhB/hmoSkTWMXiVcftAGWMVxuwdE2A2jLIPv1R0++EbzQqaPAA9nIdP74c4EchA44X/p3Dv2sHeaYShY9wSHf8K7uI+ILnl7jssNwXmxvjZbEpUPvbldvkVO+IhUh6MEqPXJElNjRUjFAnoOXJe+uSMnqujE8jUPpsKLkkIJmeUmmnIOIZ1D063qCZoj1V7uKZq/GhV+JnZD6geo7sCQf1UW6hdwK50KbrVZetXUg0bxUz30dpY3WB5a/BJC0/+2QxEMq/p30YYTExRdMcdbDy8Nfgp/T1M5nkd9/5YTyulZCsacvvFNytrkS86kpmB++zoPwHPMKG6CDNY8JuMPbmJhMSvErhUHWY+1Au50uN7Qi0nGq5yltuLZIj/HEvFhAQx5iGV9fBZZ2Vz39Q9+DYFvswS6q7ahZb2LvEUxjgrgtcJV13SIEXg9SWB2VP156YFfOsNDjBSvnmnOiN3sH4WDShCyXiGeisIxOUeA2xs/cDAPwUoimBMOn1qnqD9NT9CGAeSdvX8q6qm+bU8dH2F9ZRRDIFojm7DRwgSnaECxomXw=",
        "bitsUsed": 1024,
        "bitsLeft": 895974,
        "requestsLeft": 199980,
        "advisoryDelay": 1000
    },
    "id": 26066
}

The method shows which part of the RANDOM.ORG API was used to generate the true random blob. The hashedApiKey allows the client to share the full contents of the random and signature objects with third parties without disclosing its apiKey. The n parameter from the request is included too. Note that the format property has been added, even though it did not appear in the request. The data array within the result contains the random blob produced. Since no value was specified for the format parameter, the blob is encoded with the default base64-encoding. Note that the completionTime specifies UTC time zone (‘Zulu time’) by the letter ‘Z’ after the clock time. By returning the value 69,271 for serialNumber, the service indicates that this is the 69,271st request to have been completed with the apiKey in question.

The result object contains a signature of the entire random object, which allows the authenticity of the random object to be verified. Through the other fields in the result object, RANDOM.ORG also advises how many true random bits were used to satisfy the request (1,024) and how many bits (895,974) and requests (199,980) are left in the client's quota. It also advises the client that it can go ahead and issue the next request after a short delay (1,000 milliseconds).

Example 2

The following requests four blobs, each containing 6,144 true random bits (768 bytes) encoded as hex strings.

{
    "jsonrpc": "2.0",
    "method": "generateSignedBlobs",
    "params": {
        "apiKey": "00000000-0000-0000-0000-000000000000",
        "n": 4,
        "size": 6144,
        "format": "hex"
    },
    "id": 12482
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "method": "generateSignedBlobs",
            "hashedApiKey": "oT3AdLMVZKajz0pgW/8Z+t5sGZkqQSOnAi1aB8Li0tXgWf8LolrgdQ1wn9sKx1ehxhUZmhwUIpAtM8QeRbn51Q==",
            "n": 4,
            "size": 6144,
            "format": "hex",
            "data": [
                "80a82b702a02d2e3bdaf8d28ade7aef709e2a88666b4f5f3072b88f33ec52f0661106ce57764a7962869f20c4f35aac5dfe5d2e38638e849040db219dc4e2de7924405957511c5ae5a5e20c5cd73dafe4b7af48b911580efe898d7371af1b9cae3fd66132b725ec9a625ddfabdd00eae55d662d23dc841296976d405c09e4deebefb40ec48f21f10b9a0f51cf3417073f2ad9deb1b13db1c70731bdfd9197a05aaf4b21f4fa25507b73f82cd67950cc4c8ed2a8c8bc64a7cd34d050544f9c001bf06823ea85cbc841e27195a500dcb7946357c6adbf2b1f5e44538bf2f47f5706b4e83583c830090675e7489540f2d2e330d9dec0af5e3dd70fa3a8050fa710005b6a84d46886d1e3c75e21038794436638f557e46334c7d94b14ec7b4d747c89e51c7e022b75515b1a853ce0b622f8978f25cb93f916ca9ef188a44e3f8f52e7f8ed88c8dfa2724aafb97e9f0d135f79874b80680635eb392f63fc0bf755e76d5de2fe45b8d841aba8a231a564ee36bacd1ecac07ab9302b8fa526e2644eba6973e1c79e0cbd296c03c8bb952a6d325bf8f6af9f40c6e40a1a9b105ae9b6b2b0810559aa6d65cd7e646dc54341cad727aa198456cbbc9ebc11b0ae8c4e071b5258150a009c28805c49d48522341abc1bdb59733f51994ddddcb8af86c02cfd60e661b207a9556fe9c47d176ad3d4cac33284fae4eb32db205e09b3ef911c9df237e7b323602bd1ae8fb284c30c8bc1f902512ac233a6eaad889ae06617fe6fd80210c20a52d2baf03ca40c5c772cc6aa6fa7d2f5fb617f230c33e082c5518b439f89476d2958505cd256cd3c028c45814859368ae1473bb7330fb12ae0f786823ecdee1f732c3915bd2be99b0336e45c68dd1a431944bfcf0078d0e0fe7c83728231b709d017c528b2b52737bc2488a2153b584d9bd5746af1726e578065257b87449d5b08032b4e2c05185dba93ea4eae72861f0c374dfd8f3ee8b0fd1fa91ded64be41d28708603abd80eeba6accd462c13e1d558cd1409ec97ce29abbeec060e4e6f40c64c6df36fac4b357c7b1a32fa670548116856a1dc31189a28e711",
                "c3a8b43ece0a94a7d153019bdc8023cd920bd46170f25d8c51e9e72d5d4c8dbc506fcb13dce388a6ade605a2c44bbb65f3b93896a755314faea6ea9b3b78b18787c1d160f672ba1196dc1d952168215c7c4654b10acf0617002f9c853e6bd8c31310d10ecb6645f01d6d84edb9ebdb7122b5a468fce64e55befaca922332ff0bb6599c5c3be334e6c879e1e10e55ee4b926b527b0b34367788966c89aa915ed9672cf8199679380ebb8effd6c73b5901977ec09e1d1f097fc35642ba15c8eb960fbe50f570b652f87014b4238e5fca3e779e7fea8518eb86d159eeee89f92c4409c2ccea60b0711c02769bce14d53c468d0e54e096719fad7bf20457024fe9626a0dae13327d8fea2b2a6f59193ce772ec91f7eb73a4cfd6d3675ebb20d4d2bfaf02bbdb3c303ec264a833e1d13be44c83c0c2f592cb1896e9635711e3977ba7e17eaa9e05b6b4eb8e48929643917e8d6ed98777b66e2ae6d7dcd1d62b0979d6cd7d8350efd928d86ff697355c9584678541dce276d04faa2368cc2eab84a79aae35cdeb341c9522335c15e44da0c980bbbe4d4fe2651c279d4f98aa53d6b54722cf4b27b5f7a0a4647fc31b5dd6321ff343282d63f2706db08600222c688addc5cd14ab4d03da20f07523fe9e2cd87982b99756b123453ce28dd3cc21c588b26d61cbaf0ef30dc9248c64aadb26cac5bae04a91a145d12e9913fc1adfefe5b601386236dcb52ec5c43a5c8e9fc782413378caf9d4de4bfc31dafc2df94a6a53f60afca176730a58d28b4d1d7f5f684e720db9528bda169c40b25393ed46fb93ae8e4727a99717b58f6f0127d1eae4dec9487e2b5501b83eba74e5be59c8cad18141b3b42594b77fda77ec90c6fa69b3fbd0a4f78fc4f848618f9984376077834883e1757c3cf4b571302efd954e03bb2222204332b33d4019ec6cff5140554d07b84f0fed6e0292b45028ce2c65f11ffa9f467ed5a94440dc327a964ad810a8f6b14e6412eb459042ea8a4b4617690e7b3f2101ad89fd0ce4769fcf115d7f828014d0e02425bed066e4bf1db9cadba9ca78566bbae551a2d91dff3ec9c8f082",
                "d14b4d147bba4ed90a249718f72f7c1f3bfef7771d7500a032c214b7550516e676e3692da25cfe7728c866910ffeaa1e81a5a5bf9d45301b984729275536634353a60830c50166f12ab7e58e6294b0e3162a59acd876245f4e0e04e376c555f4b1de6b104d2c8cfc7b6141f7f60820577a736c67d0fe890bac5427a464b524e163f5e46abcf9f21d7c5cc93eb62f22f4e8ed3ae0d2f505db1d88ac3e2c2fdd4850ac4efa7a21b78bd7c733a8f62d24e87a6204b74f4e5721a8227171381f62c938832fc356fc03d76982c65335ebfe66011cc61fe6efd49e919316e1cc38f56f4e2bea300f3d07c17e27e8025b072b1597a4582a0f26513bc9bc4ed64a0cf316b56f81d0451aed47da9ba468e2055aa60589995ee82c0b2f452de4b02158e29f0e2230dd6a88a298efc90ab624eeac5d3267252b4f5cb87380f6e02c2f7d3cf0160094aec2d9975db6fb751a6fd0fc147cb8a99d560e78aa58e78252cf56e9247b70751378adee2037c2f50511ca1d90a0c0edaa3644b5a5c28195720d6dd9be0a2b00268e56fcaf17e590931456f2e34428a0406ffe827ee0929211a2f39f9b919aa859c9cac81578bcbbee59fd5facc3f8ca628884e3864d9c1aafb527d7aa79061a732b7e395384d9f42ab2c5d6aa70ea347c2cc7292c125c4aaf0b4bdef4ef2f363efa60a4a2fd7d0d03869e88eac8f9f4e00dcbb418dbe6e562b47585bab5ae4baba13415ef50857d5ac066f407ea54d671e7db3c2d90c0a8126bf9fed058aa804fc3bec327efe48278b90898c4e0cdf123386b67a0495ccb378bf58451e05c410b322f32f640656ba97754503c97f1a26af8e45bdba9ee27c72d5be0ed987413f3c62d32c1f4e5d1cb12fe9f2ada75c8a59525fde4d564dbfa8548118f4e8aec766d12fad6f0e7f44f373a22de176a8b01bee86c010dbdf514569270abd107c9675f9f273bd882f95000c9375628516d8d8e9e86df8ad3c037f585daabe395563da8cc5bd07ecb53fe41f1356326b93722ec0e84d017d32a41eea918b1a385b03ac467e668c5c0409d124d494b77d7c1a4113839648e7be294261efb2e",
                "787239f42e67db4fafb71dbadac7337d0f2ef7d80459bca47e3f597775ee77672593f64965598aa3cd59298dec75cbaf9cd171588c4618d4209aea167a9e8d6d2cd865373b2ffa86a1d64afcd5b3fa6e53a09b4f1ed68bfcf99ad665d20ad95d7b4878ea8a765bc31a8faf6dfed32a6ad4b4463fc3e80825eedb195e551038395ea1cbc97623a21edc9b23d82ffd1a8c0fbaeae9688c555e4837c69b4c236181ddd9dbbec6a8905a6e534500c40ba2e16c9b7cbeb1a908389403d4183c064518b7b51c3d1b158ba215deb242dcc83fbe355e9f69db7c086cecaa444af38dd754744236234739da64e382258d2a10c297798985dd06008fe732a175c634e75c43dc489603187d935a381d0f578e39b330c17b43a51099e143954c15fd7aa0beab550ed9e20c7e80e2b32437841e0dbede9d987232b52200e8927d46a8504ca53d095556c97aad23abf7d0fe5cc1b5adf547e65d2e023e7dbcdfc9cf618f553e0cfcda004d22e065cff2d32f808ae90d99711c21173d1f19fa6cebaefc559b4e8ef386cec1c51b5e6d4e905d71cfff8cf05790afdcdb2f38d5e5f60d0032309d3ba60e2f3fe7d6d885cd89d9039a4680501f6f5eecd108683eea4696fc0c2c901db665f5ec45cfb1e66a03dfe76e1044b6fcf6cd609908261c19fe863bda0f0125980cabc46f07364818bcc9c186034ddef796e4f4cc88c6744abff9e610cd9001a1f9b01c6b0382c7f3f95ec9c0685336f33c058152d9dc3f41e31e3c4104437e756c8cc7f4a7d6dbb845113fd5ff52432b3a99a5530f32af0dbca67077854c6ef7a5e028db68d789f2fd407db3f02d5cd6d79f67015ceb42636ee4c3b9c961df330886877141873f5c1322f3c53243f15b6564cdf62741fb223f36507218d1c24384a50fe2ccc479e22ff79168ba390b85126544148165c7aab3bb291301a322a71402ff130aa17947afdd6c925aa515f7e410fde294d02e9a477169e81e75c53db75181aebab4baa177abab528a18eabb55b71030028c2c4a0e54967186fb974ffc95c475b72f8747199c6aa84a1db92c357ffd727ce00e0985d9c94ea3e4ec"
            ],
            "completionTime": "2013-09-30 17:48:47Z",
            "serialNumber": 69272
        },
        "signature": "HuRLqY4sNiPj7W1tKIAIV4rPDBPxWvLxQfnHehk1Xl2PynVyDt288Po/Jz1LltSJQ1EOxHKR/44ZZk2hsk1n6ePf1hbTVdxBLvf1RbyzzaamTAsQKmrrnQXcMIyXa/db7GDlgMnBtcMlIs3jDQlgbUcUB9+CsQdUJEa8hJU/lHqJbXEQXVVfqtZLbt9EkMXdy9a3EJVcgV62vkNEzCFaVzZlJ/cdaNkWDH9aUlaCHrm2DyueeDsCSd7KfMD52+XCHMePHjLEcAvrjraMggB0FKrkzkEJQCH5zkAl9NnQjyYbZSi6kGnoknEG1OSgDL/ddzBs+hwYPBe3PZrEb6LlSCzclTCihKag2dsmmsMiVJRzPWjB0Dxj/lYU8E3Km2QR4lgVBxxd2MrLXLweF+Y11cSAcIWUN7NC/ZO62pImEf6osndeUlLEHQjr+wHOzLWInDX04xynEGJR/64sYvThmD+BwOB5xSJzm7y+IxgcjVKwNwsAxgjRebZ3XFnzzgKmTF+LuSuopUSM5KHzBoC21qSeb45uS5ASgUBwthOdjG11ci5X4UptH8wJiAuUVWPyAX33lc1TurxiJLIFt/fyJkHvYiD9BJvlyCCuwFDh/NRBcgY47VQL503XSSXlLwkfBoxXIyPQBu8ADD55RMC9GeQVyZFDGpvYn2ocvkVSeFg=",
        "bitsUsed": 24576,
        "bitsLeft": 871398,
        "requestsLeft": 199979,
        "advisoryDelay": 1000
    },
    "id": 12482
}

The method, n and format parameters are the same that appeared in the request. The hashedApiKey allows the client to share the full contents of the random and signature objects with third parties without disclosing its apiKey. The data array within the result contains the random blobs produced, formatted as hex strings. The service advises exactly when the request was completed and that this is the 69,272nd request to have been completed with the apiKey in question.

The result object contains a signature of the entire random object, which allows the authenticity of that object to be verified. Through the other fields in the result object, RANDOM.ORG also advises how many true random bits were used to satisfy the request (24,576) and how many bits (871,398) and requests (199,979) are left in the client's quota. It also advises the client that it can go ahead and issue the next request after a short delay (1,000 milliseconds).

verifySignature

[+]

This method verifies the signature of a response previously received from one of the methods in the Signed API. This is used to examine the authenticity of numbers. Your client must set the method property of its JSON-RPC request object to verifySignature. The request must also contain an id member, which will be returned in the response.

Required Parameters

The following parameters are mandatory and should be specified in the params array of the JSON-RPC request:

random
The random field from a response returned by RANDOM.ORG through one of the Signed API methods.
signature
The signature field from the same response that the random field originates from.

Optional Parameters

No optional parameters.

Successful Response

If the signature was examined successfully, RANDOM.ORG returns a JSON-RPC response with the result property containing an object with the following named values:

authenticity
A boolean value, indicating true if the random numbers were authentic RANDOM.ORG numbers or false if they were not.

For a successful response, the error property is absent.

Error Response

If an error occurred, RANDOM.ORG returns a JSON-RPC response in which the result property is absent and the error property contains an error object as described above.

Example 1

The following requests validation of the response from Example 1 from the generateSignedIntegers method description above.

{
    "jsonrpc": "2.0",
    "method": "verifySignature",
    "params": {
        "random": {
            "method": "generateSignedIntegers",
            "hashedApiKey": "oT3AdLMVZKajz0pgW/8Z+t5sGZkqQSOnAi1aB8Li0tXgWf8LolrgdQ1wn9sKx1ehxhUZmhwUIpAtM8QeRbn51Q==",
            "n": 6,
            "min": 1,
            "max": 6,
            "replacement": true,
            "base": 10,
            "data": [
                3,
                6,
                4,
                6,
                1,
                5
            ],
            "completionTime": "2013-07-07 09:00:43Z",
            "serialNumber": 69149
        },
        "signature": "Pd46xecjlt/EEOdNGFQNCFHVJhZ5lfVUFLziDusOpLIKGbbHh4kCRM8+el8xh3ASUgR7qfL+K7pzERsIIHIheiIt8EXq9Xr/DW3N3qfKL/4Cai+zyBGn4xThSJnXSJPvM+LuXI+B2dPx7GYJa2PSVgF+fV3j0eN+exAa4fjAQFGiPDQo+dCQO3cSO8aZ76tSGJpo/6b1rR/sdIt8uAWRsfL56tFA+2+xUtuXU5vM8HT+KO6o4N7TWpvBz1rw/0S9iiIRdIDJ5M/AjKXeXKMMkDBHUaeUWCDEZkZOMYTk6IvOpERlsWz0dz2xrs4NE8vZsi4nIVU5izGLYceMRf2TmZVC7XXdZDbeEnJnCmDacRBONqTYklJ22wGrXrFs8GElEoG3IqOgjS1ZME3/jBGW7G3eUB1xb0lT773V2YvGBPTqsnz3tawO8UDdIpoGjSQjtgql/j7gzNmyW6AC9wvrLyXeh7OP6rhp3SLNUAjNhr+QqjHrqPEv+QqkZspYCxTMVyRILCe+z+jTbNnTClVpgxIP5hSfLkinea/TpomZqWj6KwYPqKuiNMrEXsbWlAytzr1v1tsbHbESb2XKytUDWHqmBDCNxHphcgVTmn9+bi2+WPjueBBUH+b0ZOvHIZNxld9P76x8IlcOVKRLl770j0yD3ActIZNaHvUNYeBoK2M="
    },
    "id": 28782
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "authenticity": true
    },
    "id": 28782
}

The value of true for the authenticity field indicates that the random value specified as part of the request was indeed signed by RANDOM.ORG, proving the authenticity of the numbers.

Example 2

The following requests validation of the response from Example 1 except that the first integer has been modified from a 3 to a 6, as you might expect in a tampering attempt. The other values in the random field have not been modified.

{
    "jsonrpc": "2.0",
    "method": "verifySignature",
    "params": {
        "random": {
            "method": "generateSignedIntegers",
            "hashedApiKey": "oT3AdLMVZKajz0pgW/8Z+t5sGZkqQSOnAi1aB8Li0tXgWf8LolrgdQ1wn9sKx1ehxhUZmhwUIpAtM8QeRbn51Q==",
            "n": 6,
            "min": 1,
            "max": 6,
            "replacement": true,
            "base": 10,
            "data": [
                6,
                6,
                4,
                6,
                1,
                5
            ],
            "completionTime": "2013-07-07 09:00:43Z",
            "serialNumber": 69149
        },
        "signature": "Pd46xecjlt/EEOdNGFQNCFHVJhZ5lfVUFLziDusOpLIKGbbHh4kCRM8+el8xh3ASUgR7qfL+K7pzERsIIHIheiIt8EXq9Xr/DW3N3qfKL/4Cai+zyBGn4xThSJnXSJPvM+LuXI+B2dPx7GYJa2PSVgF+fV3j0eN+exAa4fjAQFGiPDQo+dCQO3cSO8aZ76tSGJpo/6b1rR/sdIt8uAWRsfL56tFA+2+xUtuXU5vM8HT+KO6o4N7TWpvBz1rw/0S9iiIRdIDJ5M/AjKXeXKMMkDBHUaeUWCDEZkZOMYTk6IvOpERlsWz0dz2xrs4NE8vZsi4nIVU5izGLYceMRf2TmZVC7XXdZDbeEnJnCmDacRBONqTYklJ22wGrXrFs8GElEoG3IqOgjS1ZME3/jBGW7G3eUB1xb0lT773V2YvGBPTqsnz3tawO8UDdIpoGjSQjtgql/j7gzNmyW6AC9wvrLyXeh7OP6rhp3SLNUAjNhr+QqjHrqPEv+QqkZspYCxTMVyRILCe+z+jTbNnTClVpgxIP5hSfLkinea/TpomZqWj6KwYPqKuiNMrEXsbWlAytzr1v1tsbHbESb2XKytUDWHqmBDCNxHphcgVTmn9+bi2+WPjueBBUH+b0ZOvHIZNxld9P76x8IlcOVKRLl770j0yD3ActIZNaHvUNYeBoK2M="
    },
    "id": 28782
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "authenticity": false
    },
    "id": 28782
}

The value of false for the authenticity field indicates that the random value specified as part of the request was not signed by RANDOM.ORG, i.e., the signature is not valid.

© 1998-2017 RANDOM.ORG
Terms and Conditions
About Us