Management APIs

Customers may make use of HTTPS management APIs for specific administrative operations in GreenRADIUS. These allow customers to write their own frontend software to administer their GreenRADIUS instance.

This document lists the endpoints for these APIs and provides examples of how to call each one.

All of these APIs require that the management API password be configured. You can do this by executing the following command from the shell on your GreenRADIUS instance:

sudo docker exec -it GRVA-MAIN changepassword grsapiusr

All requests require parameters to be supplied in the request body as a JSON structure. The Content-Type of the request must be set to application/json. Authentication is required for each request in the form of BasicAuth username/password tokens.

For example, to call the API from Python, you could use the following:

import requests

HOST = 'greenradius.example.com'

requests.post(
    'https://'+HOST+'/gras-api/v2/mgmt/import_token/yubikey',
	auth = ('grsapiusr', 'GreenRocket!23'),
	json = {
    	"yubikeys" : [
            {
                "make": "Yubico OTP",
                "serialno": 3014781,
                "publicname": "ddvcuttiuejt",
                "internalname": "8b428d0f016f",
                "aeskey": "a55adb9c4da2ad57c529737fd4d5ecd0"
            }
        ]
    }
)

The APIs are:

Import a YubiKey Token
Delete a YubiKey
Delete an OATH Token
Assign a Token
Assign an OATH Token
Unassign a Token
Request Token Assignments/Status
Request Authentication Records
List Block/Unblock Status
Unblock Users
Enable Token Assignment
Disable Token Assignment
Add a Temporary Token
Update a Temporary Token
Delete a Temporary Token
Get Temporary Token Information

Reporting Batch Results

Many of the endpoints allow one to send multiple entries as part of a single request. For example, the YubiKey Import endpoint enables you to send several YubiKey token entries with one request. When this happens, it is possible for some of the assignment requests to succeed and some to fail. Therefore, these endpoints use result batches to report the results of individual logins, rather than reporting the entire batch as a single success or failure.

A result batch is a JSON structure with the following entries:

{
    "count": 2,
    "records": {...}
}

The count is either an integer or a string (callers must expect either.) It indicates the number of results in this batch. The records entry is a JSON structure, unless count is 0, in which case it is the empty list []. It will contain count key-value pairs, each of which represents the result of one of the entries in the initial request. The value will vary depending on which type of batch and which endpoint; the key is always a string (not an int) of the index, starting from 1, of the request in the initial list passed to the endpoint.

For example: say a fictional endpoint square, which computes N², is called with five individual entries:

{
    "numbers": [
        5,
        2,
        "invalid input",
        6
    ]
}

The result might be two result batches, one containing successes and one containing failures:

{
    "numbers_squared": {
        "count": 3,
        "records": {
            "1": 25,
            "2": 4,
            "4": 36
        }
    },
    "numbers_invalid": {
        "count": 1,
        "records": {
            "3": {...}
        }
    }
}

numbers_invalid["records"]["3"] would be an error structure, as described below.

Paging

When multiple entries are returned by any endpoint, you have the option to request that the results are paged: that is, rather than returning all the entries in one request you can fetch them in slices.

To prevent denial of service, all entry batches are truncated to 10,000 records: no endpoint will return more than 10,000 records at once. This means you must implement batch handling if you need to deal with more than 10,000 results.

To use paging, specify the following two options in the JSON parameters to the endpoint you are using:

Key	Value Type	Value Description
`offset`	Int	The offset from which to start the returned records.
`limit`	Int	The maximum number of records to return.

For example, if a query produces 50,000 thousand results, you can fetch the first 10,000 with:

{
    "offset": 0,
    "limit": 10000
}

Then, send another request with the same parameters except the next value of offset:

{
    "offset": 10000,
    "limit": 10000
}

Once a return value contains fewer than limit requests, you have reached the end of the available entries.

Error Reporting

Error Structure

Errors are reported as a structure with the following entries.

Key	Value Type	Value Description
`code`	Int	An integer numerical code describing the error.
`short`	String	A short, non-user-friendly description of the error.
`description`	String	A longer, more user-friendly description of the error.

Table of Error Codes

Code	Error
4000	The `Content-Type` of the request is not `application/json`.
4001	One of the input parameters is invalid.
4002	A required input parameter is missing.
5000	No user found.
5001	The user already has the maximum number of tokens allowed.
5002	The token is already assigned to the user.
5003	Assigning a token to a user failed.
5004	The requested YubiKey token is not present.
5005	The maximum number of users has been exceeded.
5006	The token could not be assigned because user-level authentication failed due to invalid credentials.
5007	Token assignment failed for an unspecified reason.
5008	Token assignment failed because the token does not exist.
5026	The requested assignment was not found.
5051	The YubiKey token is already present.

Attribute	Type	Description
`make`	String	The make of this particular token. Should always be set to `"Yubico OTP"`.
`serialno`	Int	The serial number of the YubiKey.
`publicname`	String	The key's public ID.
`internalname`	String	The key's private ID.
`aeskey`	String	The secret AES-128 key associated with the YubiKey.

Parameter	Type	Description
`deletealways`	Bool	If `true`, the YubiKeys will be deleted even if they are currently assigned to users. If `false`, those requests will instead produce error entries. This parameter is optional and defaults to `false`.
`yubikeys`	List	A list of YubiKeys to delete. Each YubiKey is a JSON structure with a single entry `publicname`, which is the Public ID of the YubiKey.

Attribute	Type	Description
`username`	String	The username to un-assign from, in `user@domain` format.
`publicname`	String	The public ID of the token to un-assign.

Attribute	Type	Description
`status`	String	For successful unassignments, holds `"success"`.
`publicname`	String	The input public ID of the token.
`users_unassigned`	List of strings	A list of all users the token was unassigned from.

GreenRADIUS v5.2 Admin Guide