EaaS API Overview

Real Random provides its EAAS (Entropy As A Service) via a set of REST API calls that a partner or client can use to retrieve or publish entropy. This guide will explain how to integrate EAAS into an application.

Architecture

The EAAS server provides a REST API for both producers and consumers of Entropy. REST API’s conceptually follow the following steps:

1. Application authenticates to the server using its ID and Secret (obtained out of band) over HTTP/S
2. Once authenticated, the application then has a token to use for subsequent requests.
3. Application either requests Entropy or publishes Entropy to the server
4. The token can be used for multiple requests and the authentication step doesn’t need to be repeated until all data has been transferred.

API Authentication

To authenticate to the EAAS Platform, you must have API key credentials and use them in your application.

The authentication with API key credentials follows The OAuth 2.0 Authorization Framework and uses its Client Credentials flow. According to this flow, the application must use the API key credentials to request an access token and specify the received access token in the Authorization header according to the Bearer Authentication scheme.

If, for example, the access token specified in the Authorization header is expired or your API application is disabled, the API will respond with a 401 status code and error details.

Obtaining A Token

This example will be assuming one is using Python.

1. Store the client credentials that you have obtained from the EAAS administrator.
   >>> client_id = ‘<your client ID>’
   >>> client_secret = ‘<your client secret>’
2. Store the URLs of the EAAS server. These URLs will be used for authentication and requests.
   >>> eaas_auth = ‘https://auth.realrandom.co’
   >>> eaas_api = ‘https://api.realrandom.co’
3. Encode the client ID and client secret string using Base64 encoding and store the result in a variable
   >>> from base64 import b64encode  # Used for encoding to Base64
   >>> encoded_creds = b64encode(f’{client_id}:{client_secret}’.encode(‘ascii’))
4. Define a variable named basic_auth, and then assign an object with the Authorization key containing authentication data to this variable.
   >>> basic_auth = {
   …        ‘Authorization’:  ‘Basic ‘ + encoded_creds.decode(‘ascii’)
   …    }
5. Send a POST request to the /o/token/ endpoint. The request should contain authentication data in the request headers and contain the grant_type field set to client_credentials in its body.
   >>> response = requests.post(
   …         f’(eaas_auth)/o/token/’,
   …         headers={
   …           ‘Content-Type’: ‘application/x-www-form-urlencoded’, **basic_auth
   …            },
   …        data={‘grant_type’: ‘client_credentials’},
   …        }
6. Check the status code of the response.
   … response.status_code
   200
   Status code 200 means that the EAAS server has authenticated the API client and issued the API client a token for accessing the API endpoints(an access token). The response body text contains an encode JSON object with this token and some other information.
7. Convert the JSON text that the response body contains to an object and then store this object in a variable named token_info.
   >>> token_info = response.json()
   >>> pprint.pprint(token_info)
   {‘access_token’: ‘’eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImMwMD…’,
     ‘expires_in’: 36000,
     ‘scope’: ‘read write groups’,
   ‘token_type’: ‘Bearer’}
8. Define a variable named auth, and then assign an object, that will be used for constructing an Authorization header in API requests to this variable.
   >>> auth = {‘Authorization’: ‘Bearer ‘ + token_info[‘access_token’]}
   >>> auth
   {‘Authorization’: ‘Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI6ImMwMD…’}
   You will need to specify this variable in every request to the API.

Requesting Entropy

This example will build on the “Obtaining a Token” example. Again assuming Python.

1. Authenticate to the EAAS Server
   The following variables should be available now:
   >>> eaas_api   # the base url
   ‘https://api.realrandom.co/’
   >>> auth   # the ‘Authorization’ header value with the access token
   {‘Authorization’: ‘Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI6ImMwMD…’}
2. Send a GET request to the /api/entropy/ endpoint:
   >>> response = requests.get(
   …         f’{eaas_api}/api/entropy/’,
   …         headers=auth,
   …        )
3. Check the status code of the response:
   …   response.status_code
   200
   
   Status code 200 means that the request was successful.
   Also the response body contains the returned entropy as JSON text. When converted to an object it will look like this:
   >>> entropy = response.json()
   >>> pprint. pprint(entropy)
   {‘data_256’: ‘KIWb1hQqrHrmvRktG7AVkVJIBTqcc3ceazzD48uoC9g=’,
    ‘data_512’: ‘IwTrccZOB6F6YKO5YwzN+gQ38bXIcccfJZZf/lRZjOWoBnjslVcvHlmgPgYusiGxDt4k81PwAQfNEThyXfG4Lg==’}

Publishing Entropy

This example will build on the “Obtaining a Token” example. Again assuming Python.

1. Authenticate to the EAAS Server
   The following variables should be available now:
   >>> eaas_api   # the base url
   ‘https://api.realrandom.co/’
   >>> auth   # the ‘Authorization’ header value with the access token
   {‘Authorization’: ‘Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI6ImMwMD…’}
2. Send a POST request to /api/publish-entropy/ endpoint:
   >>> response = requests.post(
   …                 f’{eaas_api}/api/publish-entropy/},
   …                 headers={‘Content-Type’: ‘application/json’, **auth},
   …                 data=entropy_data,)
3. Check the status code of the response:
   …   response.status_code
   200
   
   Status code 200 means that the request was successful.