GoAdmio

api

Import API keys from an XML file into the GoAdmio panel's API database

On this page: Overview · Quick start · Syntax · Arguments · XML format · Output · Examples · Troubleshooting · Details · See also


Overview

/go/api adds API keys for the GoAdmio panel. You describe the keys in an XML file, and the command:

The command only adds or replaces keys. It does not list or delete them.

[!WARNING] The XML file holds your keys in plain text, and each printed URL contains the key. Treat both as secrets, and delete the file once you have imported it. Only import files you wrote yourself (see Details).


Quick start

# Import the keys in an XML file
/go/api /root/api.xml

Syntax

/go/api <file>

The command takes one argument and has no -- options. It needs xmlstarlet and jq to be installed.


Arguments

Argument Required Notes
<file> Yes The path of the XML file. It must be readable by the user running the command.

XML format

The first element inside the root element decides what the file contains. For API keys, it must be named API. The root element can have any name.

<?xml version="1.0" encoding="UTF-8"?>
<APIs>
  <API>
    <Name>My Integration</Name>
    <APIKey>0123456789abcdef</APIKey>
    <Command>example</Command>
    <IP>203.0.113.10</IP>
  </API>
  <API>
    <Name>Second Integration</Name>
    <APIKey>fedcba9876543210</APIKey>
    <Command>example</Command>
    <IP>198.51.100.7</IP>
  </API>
</APIs>
Field Notes
Name The name of the key. An existing key with the same name is replaced.
APIKey The key. It must be exactly 16 or 59 characters long.
Command Stored with the key.
IP Stored with the key.

If the first element inside the root is not API, the command does nothing.


Output

Message Meaning
API URL: https://go.domain.com/api/api.php?Name=<name>&APIKey=<key> The key was saved. The name is URL-encoded.
ERROR: API key length <n> must be either 16 or 50 characters The key is the wrong length, and it was not saved. See the note below.

[!NOTE] The error text says 16 or 50, but the check accepts 16 or 59 characters. A key of 50 characters is rejected.

The host in the printed URL is the literal text go.domain.com. Replace it with your panel's address when you use the URL.

The command always finishes without an error status, even when a key is rejected.


Examples

# Import the keys
/go/api /root/api.xml
# Delete the file afterwards, because it holds the keys
rm /root/api.xml
# Review the log of past runs (the log shows the file name only)
tail -n 20 /var/log/go/api.log

Troubleshooting

Symptom Likely cause Fix
Nothing is printed The first element inside the root is not API, the file path is wrong, or the file has no entries. Check the file against the XML format.
xmlstarlet: command not found xmlstarlet is not installed. Install xmlstarlet.
ERROR: API key length ... must be either 16 or 50 characters The key is not 16 or 59 characters long. Use a key of exactly 16 or 59 characters.
The URL starts with go.domain.com The host in the URL is fixed text in the script. Replace it with your panel's address.
jq: command not found, and the URL has an empty Name= jq is not installed, so the name cannot be encoded. Install jq, then import the file again.
An older key disappeared A new entry with the same Name replaced it. Use a different Name for each key.
A key was saved with a field from another entry An entry left out a field, so the value from the previous entry was reused. Include Name, APIKey, Command, and IP in every entry.
An entry with a quote mark in a value fails or misbehaves Values go into the database statement as typed. Avoid quote marks in values.

Details

What it does for each entry

# Step
1 Read the name of the first element inside the root, and count the elements with that name.
2 For each one, read its child elements into shell variables named after them (Name, APIKey, and so on).
3 Skip the entry unless the first element is API.
4 Reject the key unless it is 16 or 59 characters long.
5 Delete the row in the API table with the same Name.
6 Insert a new row with the name, key, command, IP, and the time of the import.
7 Print the URL.

Security

The command turns every child element of an entry into a shell variable and puts the values into the database statement without escaping them. An XML file that you did not write could change how the command behaves. Import only files you trust, and keep them readable by root only.

The key appears in the query string of the printed URL. Web server logs and browser history can record query strings, so prefer sending the key in a way that is not logged where your client allows it.

Logging

Every run appends the file name and a timestamp to /var/log/go/api.log. The keys themselves are not written to the log.

What a run does

flowchart TD
    A["api file.xml"] --> B["Read the first child of the root"]
    B --> C{"Is it API?"}
    C -- "No" --> X["Do nothing"]
    C -- "Yes" --> D["For each API entry"]
    D --> E{"Key is 16 or 59 characters?"}
    E -- "No" --> F["Print error"]
    E -- "Yes" --> G["Replace the row in the API database"]
    G --> H["Print the API URL"]

See also

Command Description
admin Change the admin user's password, or send a login alert for an IP address
hostname Change the hostname in GoAdmio
config Show or edit the server's GoAdmio configuration