The TeamDrive Enterprise Server architecture provides an extensive application programming interface (API) that can be used to:
- Script/automate processes that would otherwise require use of the web-based administration console
- Obtain information about various entities and parameters (e.g. user names, licenses, storage).
The API is based on XML Remote Procedure Calls
(see http://en.wikipedia.org/wiki/XML-RPC for a detailed description).
Only HTTP POST-Requests will be accepted.
Each request must include a checksum in the
URL appended as a parameter. This checksum is created by calculating a MD5
checksum over the request body appended with a server-specific salt value.
The checksum value must be provided in lower case characters, e.g. by passing
it through the
tolower() function of the respective programming language.
On the TeamDrive Registration Server Administration Console, this salt value
can be obtained from the
APIChecksumSalt system setting (“Edit Settings ->
RegServer”). On a TeamDrive Host Server, this value is stored in the
API_SALT and must match the value of the
Registration Server this Host Server has been associated with.
The general structure of the URL is:
The URL to access a TeamDrive Registration Server’s API is as follows:
The URL to access the TeamDrive Host Server API looks as follows:
<domain> with the host name of the Host or Registration
Server you want to connect to.
<md5> needs to be replaced with the
checksum of the current API request.
IP Access Lists¶
API access is verified by the IP address the request originated from. On the
Registration Server, check the setting
(see API_IP_ACCESS) and make sure that
the external IP address of the system performing the API call is included in
It is possible that multiple Providers are accessed via the same IP address.
In this case, the IP address must belong to the “Default Provider” (see
and the Registration Server setting
Admin Consol API Usage¶
The Admin Console accesses the Registration Server API in order to perform
a number of functions. As a result, the Admin Console must be granted access
to the API. The IP address of all hosts running the Admin Console must be
entered in the
API/API_IP_ACCESS of the Provider you wish to manage
with the Admin Console.
If you wish to manage multiple Providers using the Admin Console
you must enter the IP addresses of the Admin Console in the
API/API_IP_ACCESS``of the Default Provider. In addition, you must
set ``APIAllowSettingDistributor to
If you are accessing the API over a local network or a VPN, you can use plain HTTP. However, when sending the data over an insecure network, you must use HTTPS for security reasons.
On your side of the (web-) application, you must ensure that only successfully logged in users can view or change their own data. Users should never be allowed to view data from other TeamDrive Users. Only users associated with your provider code can be managed with API calls coming from your IP. For users with a foreign provider code you will receive a URL which must be displayed to the user so that they can login to the website of their provider.
API Input Parameters¶
The following are standard input parameters to all API calls:
- This is the name of the API function to be called. This parameter is required.
- Each request also needs to include a
<requesttime>which is the current timestamp converted to an integer (UNIX time).
- This parameter specifies the Provider Code of the Provider that is being accessed. If it is possible that multiple providers access the IP via a single IP address, then this parameter is required (see APIAllowSettingDistributor).
Users are identified in API calls using one of the following tags:
- The globally unique username of the user. If the name has the format “$<provider-code>-<value”, then it is a so-called “magic username”. Magic usernames are allocated by the Registration Server if no username is given. They are invisible to the end user (see the registeruser for more details.
- Use this field to search by username and the registration email address of a user. Functions will first check for the a username. Registration Server versions prior to 3.6.0 allowed an email address to be used as a username. In this case, such users will be found before the actual registration email address is searched. If the value does not contain an “@” character, then an email search is not done.
- The external reference of the user. On creation of a user it is optional.
If the value us unique it can be used to identify the user. To ensure that the
value is unique you must set the Provider setting
CLIENT/EXT_USER_REFERENCE_UNIQUE(see EXT_USER_REFERENCE_UNIQUE) to
True. A search for this value is always done in combination with the Provider code (
- The external authentication ID. It is used to identify users of an
external authentication service, such as an LDAP or AD server. The value is unique
for the users of a Provider. A search for this value is always done in combination
with the Provider code (
<activationcode>: This option is new in Registration Server 4.0. It can only
be used to identify a user if the user has not yet been activated. If the user has already been activated a -30100 error will be returned.
Note that the activation code may only be used to identify the user in API calls that explicitly allow this (check the call description for details).
Licenses are identified in API calls using one of the following tags:
- The unique license key number generated by the Registration Server.
- The external reference of the license. This value is optional. If it is unique it can
be used to identify the license. To ensure that the value is unique you must set
the Provider setting
LICENSE/EXT_LICENCE_REF_UNIQUE(see EXT_LICENCE_REF_UNIQUE) to
The <origin> tag¶
<origin> is new in the Registration Server version 4.0.
The tag indicates the origin of the API call. By default this is “API-CALL”,
but may also be: “LOGIN-PORTAL”, “ADMIN-CONSOLE”, “CLIENT-CALL” or “USER-IMPORT”.
Note that is is not recommended that you set this value unless you wish to simulate a different origin for debugging purposes.
The origin of a call may determine whether an email is sent by the API call or not. If the origin is not “API-CALL”, then by default an email will be sent (see The <sendmail> tag for details).
This tag also determines which the type of email templates used for emails sent by the API. If the origin is “API-CALL” then “web-” type email templates are used otherwise, the “reg-” type emails are used.
The <sendmail> tag¶
<sendmail> tag indicates whether an email may be sent by the API call
or not. A number of API calls generate emails, and this email can be
suppressed by setting
<sendmail> is omitted the default behaviour depends on the call.
Check the description of the API call which specifies the default
if the tag is omitted.
For those calls that do not have an explicit default, the provider setting
API/API_SEND_EMAIL (API_SEND_EMAIL) determines if the call
will send an email or not.
However, this setting is only used if the call origin (see :re:`origin_tag` above), is “API-CALL” (which is the default).
Example API Call¶
The following shell script example outlines how an API
call is generated and how the required MD5 checksum is calculated.
In this example
curl is used to perform the actual API call.
The result is printed to the console:
#!/bin/sh URL="http://regserver.yourdomain.com/pbas/td2api/api/api.htm" CHECKSUM="<APIChecksumSalt>" TIMESTAMP=`date "+%s"` REQUEST="<?xml version='1.0' encoding='UTF-8' ?>\ <teamdrive>\ <command>loginuser</command>\ <requesttime>$TIMESTAMP</requesttime>\ <username>YourUserName</username>\ <password>YourPassword</password></teamdrive>" MD5=`echo -n "$REQUEST$CHECKSUM" | md5sum | cut -f1 -d" "` curl -d "$REQUEST" "$URL?checksum=$MD5"
The following errors can occur due to misconfiguration or service failures, they may not return valid XML. Your application should handle these failures appropriately.
Wrong Apache Configuration¶
<html><head> <title>404 Not Found</title> </head><body> <h1>Not Found</h1> <p>The requested URL /td2api/api/service.html was not found on this server.</p> <hr> <address>Apache/2.4.6 (Fedora) Server Port 80</address> </body></html>
Application errors will return error messages in an XML format like this:
<?xml version='1.0' encoding='UTF-8' ?> <teamdrive> <regversion></regversion> <exception> <primarycode></primarycode> <secondarycode></secondarycode> <message></message> </exception> </teamdrive>
<secondarycode> (optional) are integer values.
<message> is a text.
Error codes regarding the API will start at -30100 (see Error Codes).
General errors with the Yvva Runtime Environment version or database connection are in the range between 0 and -23000.
If a program error occurs, the server will return an error similar to the following one:
<HTML><HEAD><TITLE>Execution Error</TITLE></HEAD><BODY> <H2>Execution Error</H2><FONT SIZE = +1>An error occured while processing your request: <BR>Primary error code: <B>-10005</B>, Secondary error code: <B>0</B><BR><FONT SIZE = 0><H3>"api_init.sys"@client line 7: ';' token expected in place of 'execute'.</H3></BODY></HTML>
Invalid requests will return one of the following errors:
Unknown IP Address¶
<?xml version='1.0' encoding='UTF-8' ?> <teamdrive> <regversion></regversion> <exception> <primarycode>-30000</primarycode> <secondarycode></secondarycode> <message>Access denied</message> </exception> </teamdrive>
<?xml version='1.0' encoding='UTF-8' ?> <teamdrive> <regversion></regversion> <exception> <primarycode>-30001</primarycode> <secondarycode></secondarycode> <message>Invalid Command</message> </exception> </teamdrive>
<?xml version='1.0' encoding='UTF-8' ?> <teamdrive> <regversion></regversion> <exception> <primarycode>-30002</primarycode> <secondarycode></secondarycode> <message>Invalid Request</message> </exception> </teamdrive>
<?xml version='1.0' encoding='UTF-8' ?> <teamdrive> <regversion></regversion> <exception> <primarycode>-30003</primarycode> <secondarycode></secondarycode> <message>Invalid XML</message> </exception> </teamdrive>