PageKite Service API Reference

By Bjarni Rúnar Einarsson 2020-06-06, 16:33

Note: This document is a work in progress, it is not yet complete!

• About the API
  • Common characteristics
  • Legacy and undocumented methods
  • A Python Example
• Privileged credentials
  • login(a, c, credential)
  • logout(a, c, revoke_all)
  • create_account(a, c, email, kitename, accept_terms, send_mail, activate)
  • create_account_with_secrets(a, c, email, kitename, password, kite_secret, accept_terms, send_mail, activate)
  • freeze_account(a, c, password)
  • delete_account(a, c, password)
  • admin_delete_account(a, c, reuse_names)
  • get_account_info(a, c, version)
  • set_account(a, c, key, value)
  • reset_password(a, c, send_mail)
  • set_password(a, c, password1, password2)
  • set_email(a, c, email, send_mail)
  • undo_set_email(a, c, undo_key)
  • log_to_account(a, c, message)
  • get_account_history(a, c)
  • clear_account_history(a, c)
• User Account Methods
  • get_available_domains(a, c)
  • get_kite_info_single(a, c)
  • get_kite_stats(a, c)
  • check_kite(a, c, kitename)
  • check_cname_kite(a, c, cname)
  • add_kite(a, c, kitename, check_cnames)
  • add_kite_with_secret(a, c, kitename, secret, check_cnames)
  • set_kite_secret(a, c, kitename, secret)
  • delete_kites(a, c, kitenames)
  • admin_delete_kites(a, c, kitenames, force)
  • reset_kites(a, c, kitenames)
  • add_dns_record(a, c, domain, rectype, value)
  • del_dns_record(a, c, domain, rectype, value)
  • set_dns_records(a, c, domain, rectype, values)
• Kite Manipulation Methods
  • get_groups(a, c)
  • get_group_info(a, c)
  • add_group(a, c, name, flags, description)
  • delete_groups(a, c, group_ids)
  • get_group_members(a, c, group_id)
  • add_group_member(a, c, group_id, user_id)
  • remove_group_members(a, c, gm_ids)
  • invite_group_members(a, c, group_id, user_ids, message)
  • join_group(a, c, group_id)
  • leave_group(a, c)
• Groups and Membership Methods
• Error Codes

About the API

The PageKite Service API is an XML-RPC interface exposed at: https://pagekite.net/xmlrpc/

Common characteristics

All API methods have the following characteristics:

1. The first argument (a) must be an account identifier
2. The second argument (c) must be an access credential
3. All methods return a 2 element array, where the first element is a machine-friendly return code ('ok' for success) and the second element is either a human-friendly error message or the result payload. When returning text for humans, the language may depend on the user's settings, if translations are available.

Some less security-sensitive methods will accept an empty string as the account identifier and/or access credential, but most require both.

Account identifiers may be any of: e-mail addresses, kite names or user IDs.

Privileged credentials

In the case where a super-user account is being used to manipulate other users, the first argument is the name of the account being manipulated, and the credential should be a 2-tuple authenticating the super-user: (acct_id, credential).

Legacy and undocumented methods

Note that any XML-RPC methods with CamelCaps are deprecated and should not be used in new code.

Any other methods not documented on this page should be considered "under development" and subject to change without warning.

A Python Example

This is an example of interacting with the API using the Python shell:

$ python
Python 2.6.6 (r266:84292, Dec 27 2010, 00:02:40)
[GCC 4.4.5] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import xmlrpclib
>>> pks = xmlrpclib.ServerProxy('https://pagekite.net/xmlrpc/')
>>> ok, creds = pks.login('user.pagekite.me', 'PASSWORD', '')
>>> ok
'ok'
>>> creds
('5a2b8499b3', 'f9a6xf7e7kbbkdeba6979f7d92z6db8f')
>>> a, c = creds
>>> ok, data = pks.get_account_info(a, c, 0)
>>> data
...

---

User Account Methods

login(a, c, credential)

Arguments:

1. a, required account identifier
2. c, required access credentials
3. credential, a string which may be empty

This method will return ('ok', (acct_id, credential)) on success.

If the credential argument is less than 32 characters long, a new credential will be generated and returned. If it is of sufficient length it will be treated as a previously issued credential and its validity extended for another hour.

The returned acct_id is an account ID which will stay valid even if kite names or e-mail addresses are changed.

Notes: It is recommended that clients DO NOT provide their own temporary credentials when first logging in, as the credentials generated by the service are known to be quite secure. Clients are also requested to limit the frequency of their calls to this method, as credential generation is a relatively expensive operation. Renewing old credentials is much more efficient.

---

logout(a, c, revoke_all)

Arguments:

1. a, required account identifier
2. c, required access credentials
3. revoke_all, required boolean

This method will return ('ok', ...) on success.

If the revoke_all variable is True, all temporary access credentials will be revoked. Otherwise, only the credential in use by this session will be revoked.

---

create_account(a, c, email, kitename, accept_terms, send_mail, activate)

Arguments:

1. a, optional string
2. c, optional access credentials
3. e-mail, required string: the e-mail address for the new account
4. kitename, required string: the domain name for the user's first kite
5. accept_terms, required boolean: has the user accepted the TOS?
6. send_mail, required boolean: send the user an e-mail with instructions and a password
7. activate, required boolean: activate the account immediately?

On successful account creation, the return code will be 'ok' and the payload will be a dictionary of account attributes including the following items:

• email: the user's e-mail address
• secret: the shared secret for use with pagekite.py
• kitename: the user's initial kite name
• expires: the Unix timestamp of when this account expires if unactivated
• password: the user's password (only provided to privileged accounts)

Possible errors: unauthorized, email, subdomain, domain, terms, pleaselogin, domaintaken

Notes:

• If accept_terms is not True, the method will fail.
• If send_mail is False, then privileged credentials must be presented
• If activate is True, then privileged credentials must be presented

---

create_account_with_secrets(a, c, email, kitename, password, kite_secret, accept_terms, send_mail, activate)

Arguments:

1. a, optional string
2. c, optional access credentials
3. e-mail, required string: the e-mail address for the new account
4. kitename, required string: the domain name for the user's first kite
5. password, required string: the password for the account
6. kite_secret, required string: the default shared secret for flying kites
7. accept_terms, required boolean: has the user accepted the TOS?
8. send_mail, required boolean: send the user an e-mail with instructions and a password
9. activate, required boolean: activate the account immediately?

Behaves the same as create_account (see above), except instead of generating a random password and random kite secret, it uses the provided values.

---

freeze_account(a, c, password)

Arguments:

1. a, optional string
2. c, optional access credentials
3. password, user's password

This will freeze the user's account; this means all kites will be removed from DNS so they do not consume bandwidth and any recurring billing subscriptions will be canceled. On success, it should return ('ok', 'Account frozen'). If the password does not match it may return the code unauthorized.

---

delete_account(a, c, password)

Arguments:

1. a, optional string
2. c, optional access credentials
3. password, user's password

This will delete the user's account. On success, it should return ('ok', 'Deleted: account'). If the password does not match it may return the code unauthorized.

---

admin_delete_account(a, c, reuse_names)

Arguments:

1. a, optional string
2. c, optional access credentials
3. reuse_names, boolean: whether to free kite names for reuse

This method requires privileged credentials.

It will delete the user's account, possibly freeing up all registered domains for reuse (if reuse_names is True). On success, it should return ('ok', 'Deleted: account'). If credentials are invalid or the domain does not allow domain name reuse, it may return the code 'unauthorized'.

---

get_account_info(a, c, version)

Arguments:

1. a, required account identifier
2. c, required access credentials
3. version, a version number may be empty or zero

This method will return ('ok', payload) on success. The payload will be a nested dictionary, like so:

• 'data':
  • key: value
• 'fields':
  • key: description

Non-obvious keys in the data dictionary will have a corresponding entries in the fields dictionary which explains in human readable language what they mean.

Some common fields include:

• '_name': the user's name
• '_email': the user's e-mail address
• '_ss': the account's shared secret

Note that the kites and groups data sections may be incomplete if this account has registered a very large number of kites or sponsored accounts.

---

set_account(a, c, key, value)

Arguments:

1. a, required account identifier
2. c, required access credentials
3. key, required string
4. value, required value

This method will return ('ok', 'Set key to value') on success. Any key returned by get_account_info() may, if the user has sufficient privileges, be set in this way, except for the user's e-mail address - please use set_email() for that.

---

reset_password(a, c, send_mail)

Arguments:

1. a, required account identifier
2. c, required access credentials
3. send_mail, required boolean

This method will return ('ok', ...) on success.

If send_mail is True, the user will be e-mailed the new password, otherwise the new password is returned in the payload of the method. Only super-users can reset passwords for their users without e-mailing.

---

set_password(a, c, password1, password2)

Arguments:

1. a, required account identifier
2. c, required access credentials
3. password1, required string
4. password2, required string

This method will return ('ok', ...) on success. Passwords must both be the same and must comply with the service password policy. Overly short or simple passwords may be rejected.

---

set_email(a, c, email, send_mail)

Arguments:

1. a, required account identifier
2. c, required access credentials
3. set_email, required e-mail address
4. send_mail, required boolean

This method will return ('ok', ...) on success.

If send_mail is True, a notification will be sent to the user's old account with instructions on how to undo the change. Only super-users can change e-mail addresses for their users without e-mailing.

---

undo_set_email(a, c, undo_key)

Arguments:

1. a, optional account identifier
2. c, optional access credentials
3. undo_key, a key granting permission to undo this action

This method will return ('ok', ...) on success.

This method will undo an e-mail change operation, allowing users to rescue hijacked accounts. It does not require the user successfully log on first, but the user must have a valid "undo key" which would have been mailed out by the set_email() method.

---

log_to_account(a, c, message)

Arguments:

1. a, required account identifier
2. c, required access credentials
3. message, required text to add to user's account history

This method will return ('ok', ...) on success.

---

get_account_history(a, c)

Arguments:

1. a, required account identifier
2. c, required access credentials

This method will return ('ok', history) on success, where history is a list of 2-tuples: (timestamp, text). The times are Unix timestamps (seconds since the epoch).

---

clear_account_history(a, c)

Arguments:

1. a, required account identifier
2. c, required access credentials

This method will return ('ok', ...) on success.

---

Kite Manipulation Methods

get_available_domains(a, c)

Arguments:

1. a, required account identifier
2. c, required access credentials

This method will return ('ok', domains) on success, where domains is a dictionary mapping available domain names to a list of capabilities for each. Capabilities are:

• 'pk': basic PageKite service
• 'ssl': wild-card SSL termination is provided by the front-end

---

get_kite_info_single(a, c)

Arguments:

1. a, required account identifier
2. c, required access credentials
3. kitename, name of kite

This method will return ('ok', info) on success, where info is a dictionary providing information about the kite, including any DNS records it currently has registered. The structure of this dictionary is the same as in the kites data returned by get_account_info.

---

get_kite_stats(a, c)

Arguments:

1. a, required account identifier
2. c, required access credentials

This method will return ('ok', kites) on success, where kites is a dictionary of kite names mapped to byte transfer counts for each. Kites which have been disabled will have negative counters.

---

check_kite(a, c, kitename)

Arguments:

1. a, required account identifier
2. c, required access credentials
3. kitename, required string

This method will return ('ok', ...) on success, or an error describing why this kite can not be added to this user.

Possible error codes include: 'domain', 'domaintaken', 'no_service', 'subdomain' and 'unauthorized'.

---

check_cname_kite(a, c, cname)

Arguments:

1. a, required account identifier
2. c, required access credentials
3. cname, required string

This method will return ('ok', ...) on success, or an error describing why this domain name can not be added as a CNAME kite for this user.

---

add_kite(a, c, kitename, check_cnames)

Arguments:

1. a, required account identifier
2. c, required access credentials
3. kitename, required string
4. check_cnames, required boolean

This method will return ('ok', ...) on success, or an error describing why this kite can not be added to this user.

Possible error codes include: 'domain', 'domaintaken', 'no_service', 'subdomain', 'unauthorized', 'pleaselogin' and 'error'.

If check_cnames is False, no attempt will be made to add external CNAME kites.

---

add_kite_with_secret(a, c, kitename, secret, check_cnames)

Arguments:

1. a, required account identifier
2. c, required access credentials
3. kitename, required string
4. secret, required string
5. check_cnames, required boolean

This method does the exact same thing and returns the same values as add_kite above, except it also sets a specific shared secret for the kite at the same time.

---

set_kite_secret(a, c, kitename, secret)

Arguments:

1. a, required account identifier
2. c, required access credentials
3. kitename, required string
4. secret, required string

This method sets the shared secret for the given kitename to secret. Setting to the special value "default" will remove the per-kite secret and re-enable the account's default shared secret for this kite.

Possible error codes include: 'bad_value', 'unauthorized', 'pleaselogin' and 'error'.

---

delete_kites(a, c, kitenames)

Arguments:

1. a, required account identifier
2. c, required access credentials
3. kitenames, a required list of strings

This method will return ('ok', ...) on success.

Note that not all kites can be deleted, some can just be disabled. The function will return 'ok' in either case, the actual result can be confirmed by consulting the get_kite_stats() function.

---

admin_delete_kites(a, c, kitenames, force)

Arguments:

1. a, required account identifier
2. c, required access credentials
3. kitenames, a required list of strings
4. force, a required boolean

This method requires privileged credentials.

This method will return ('ok', ) on success.

If force is True, it will attempt to forcibly delete name that would otherwise be kept reserved to prevent reuse. If forced deletion is requested but is prevented by policy, the method will return the 'unauthorized' code.

---

reset_kites(a, c, kitenames)

Arguments:

1. a, required account identifier
2. c, required access credentials
3. kitenames, a required list of strings

This method will return ('ok', ...) on success.

This function will reset a list of kites, reenabling them if necessary and setting their traffic counters to zero.

---

add_dns_record(a, c, domain, rectype, value)

Arguments:

1. a, required account identifier
2. c, required access credentials
3. domain, a required string
4. rectype, a required string (one of 'A', 'CNAME' or 'MX')
5. value, a required string

This method will return ('ok', ...) on success.

The domain name must match one of the user's existing kite names. Note that at the moment, no sanity checking is done on record validity, you can easily create completely DNS bogus records using this method. The time-to-live for the new DNS record will be chosen automatically.

---

del_dns_record(a, c, domain, rectype, value)

Arguments:

1. a, required account identifier
2. c, required access credentials
3. domain, a required string
4. rectype, a required string (one of 'A', 'CNAME' or 'MX')
5. value, a required string

This method will return ('ok', ...) on success. The domain name must match one of the user's existing kite names.

---

set_dns_records(a, c, domain, rectype, values)

Arguments:

1. a, required account identifier
2. c, required access credentials
3. domain, a required string
4. rectype, a required string (one of 'A', 'CNAME' or 'MX')
5. values, a required list of strings

This method will return ('ok', ...) on success.

The domain name must match one of the user's existing kite names. All pre-existing records for that type will be removed, replaced with the specified values. Note that at the moment, no sanity checking is done on record validity, you can easily create completely DNS bogus records using this method. The time-to-live for the new DNS record will be chosen automatically.

---

Groups and Membership Methods

get_groups(a, c)

Arguments:

1. a, required account identifier
2. c, required access credentials

This method will return ('ok', group_info) on success, where group_info is a list of hashes, one for each group. The hashes will have at least the following keys: 'gid', 'name', 'flags', 'description'.

---

get_group_info(a, c)

Arguments:

1. a, required account identifier
2. c, required access credentials

This method will return ('ok', group_info) on success, where group_info is a list of hashes, with one hash for each group. The hashes contain the same information as those returned by get_groups(), but add a 'members' field, which is a list of hashes describing all group members, including their names, e-mails and kite statistics.

---

add_group(a, c, name, flags, description)

Arguments:

1. a, required account identifier
2. c, required access credentials
3. name, required string
4. flags, required string
5. description, required string

This method will return ('ok', ...) on success.

The only defined flag at the moment is O which marks the group as open.

---

delete_groups(a, c, group_ids)

Arguments:

1. a, required account identifier
2. c, required access credentials
3. group_ids, required list of group IDs.

This method will return ('ok', ...) on success.

---

get_group_members(a, c, group_id)

Arguments:

1. a, required account identifier
2. c, required access credentials

This method will return ('ok', ...) on success.

---

add_group_member(a, c, group_id, user_id)

Arguments:

1. a, required account identifier
2. c, required access credentials

This method will return ('ok', ...) on success.

---

remove_group_members(a, c, gm_ids)

Arguments:

1. a, required account identifier
2. c, required access credentials
3. gm_ids, required list of pairs

The gm_ids must be a list of (group_id, user_id) pairs, each of which will be removed if found in the user's list of groups and members.

This method will return ('ok', ...) on success, and will not complain if some requested user/group pairs appear to have already been removed.

---

invite_group_members(a, c, group_id, user_ids, message)

Arguments:

1. a, required account identifier
2. c, required access credentials

This method will return ('ok', ...) on success.

---

join_group(a, c, group_id)

Arguments:

1. a, required account identifier
2. c, required access credentials

This method will return ('ok', ...) on success.

---

leave_group(a, c)

Arguments:

1. a, required account identifier
2. c, required access credentials

This method will return ('ok', ...) on success.

---

Error Codes

The following are some of the more common error codes returned by various API methods:

• bad_value: Bad value for
• bad_key: Invalid key
• bad_users: Invalid e-mails or kite names
• bad_group: Invalid group ID
• dns_error: DNS Error
• domain: Domain unavailable
• domaintaken: Domain is already in use
• email: Invalid e-mail address
• emailtaken: E-mail is already in use
• error: Internal Error
• kite_gone: No such kite, was it already deleted?
• no_account: No such account exists
• no_groups: You cannot create any more groups
• no_members: That would exceed your membership limit!
• no_root_ns: Could not find root nameserver
• no_service: Not a service domain
• not_cname: CNAME record not found
• not_in_group: You are not in a group
• pass_mismatch: Passwords do not match
• pass_short: Passwords is too short
• pleaselogin: Please log in
• subdomain: Invalid kite name
• terms: Please accept the terms and conditions
• unauthorized: Access Denied
• unchanged: Nothing has changed
• undo_key: Invalid Undo Key
• unregistered: Not a registered kite

Leave a comment

Name:

E-mail: (not published)

( (Please leave these blank: )

Your Comment:

Post Comment

We use Gravatar for commenter's photos. Get your own, it's free!