GREN-Map-DB-Node

Access Tokens

Access tokens are a security and integrity measure to help verify that only expected entities may access the API endpoints on a DB Node. They are required to allow other DB Nodes to poll for a Node’s data, and for software programs to submit GRENML/XML to import bulk data into a Node.

Creating an Access Token

Creating a token must be done in preparation to be polled by a consolidating organization’s DB Node, and in preparation for automated data submission from a source of truth into a DB Node.

From the main Admin page on the DB Node to be polled for its data, navigate to “Tokens”, in the section “Base App”.

Click on the “Add Token” button on the top right corner. The form requires two fields:

• A “Client name”, which helps a Data Administrator to keep track of which tokens have been given to whom.
• A “Token type”, which must be either:
  • “Polling”, for other DB Nodes to poll data from this one
  • “Import”, for automated submission of data into an API Press “Save”, on the bottom right corner.

The system then returns to the token list page, which now contains a new record showing the token name provided, followed by an autogenerated string as the token value. This value may be copied, and either shared securely with the Data Administrator for another DB Node, or inserted securely into an automated program as an input secret.

Supplying a Token

Tokens for Polling

Part of the process of establishing hierarchical distributed database connections is to exchange tokens from each data source. Each data source’s Data Administrator should send their token securely to the consolidating organization’s Data Administrator.

When adding (or editing) a GRENML Polling Source in the Django Admin, there is a field on the form called “Token”. This is where the token string for that polling source may be supplied.

Tokens for API

Insert the token as a ‘Authorization: Bearer’ header in the HTTP(S) request. In the following two simple examples, “" represents a placeholder for the actual token string.

Python requests Library Example

token = '<token>'
requests.post(
    url='http://localhost/grenml_import/upload/',
    headers={'Authorization': f'Bearer {token}'},
    files={'file': open('test.xml', 'r')},
)

CURL Command Example

curl -X POST http://localhost/grenml_import/upload/ -H "Authorization: Bearer <token>" -F file=@test.xml

This site is open source. Improve this page.