Note
This is for v3 of ipreg which was never released and has now been discontinued.
The IP Register web user interface is designed for interactive use, authenticated by Raven. The cookie ops page allows you to manage API cookies for automated access to the list ops and xlist ops. The IP Register API documentation has an overview of how the API works; here we describe how AP cookies work.
Warning
It is dangerous to download an API cookie. You must take adequate precautions to prevent the contents of the cookie being seen by anyone else. Anyone with a copy of the cookie can masqerade as you.
The API cookie should not be imported into a browser. Apart from being a security risk, doing so will prevent you from being able to access the IP Register web user interface, because API cookies only see a very stripped-down version.
Page structure
The upper part of the page has a table of existing API access cookies, or a note that there are none.
Each cookie has an view button which shows usage logs for that
cookie in the lower part of the page.
After selecting a cookie, you can revoke it early using the expire
button.
The renew button extends the lifetime of a valid cookie, or
revitalizes an expired cookie.
At the bottom of the form is a download new API cookie button for
obtaining a new API cookie. Keep the dowload file secret!
Format of cookies
An API cookie file contains a single cookie in Netscape format, which
is also used by curl and other tools. These cookies are managed by
the Oracle database on Jackdaw, but they are not compatible with
cookies downloaded directly from Jackdaw.
Each cookie is identified by a unique tag: a short alphanumeric string which forms part both of the cookie itself and part of its download filename.
Expiry
An API cookie will expire, and cease to be usable, 128 days after it is downloaded. You will need to manually replace or renew API access cookies roughly every quarter.
Jackdaw attempts to warn you when your cookies are about to expire by sending email to your @cam address. The first warning is sent 32 days before the cookie expires. Subsequent warnings are sent at decreasing intervals as the expiry date approaches. Warnings are only sent while a cookie is actually being used.
The expiry time in the cookie file is not necessarily correct: you can change the database's view of when a cookie expires by revoking the cookie early or renewing the cookie to lengthen its lifetime.
Jackdaw incompatibility
As mentioned above, API cookies for https://v3.dns.cam.ac.uk are not
compatible with https://jackdaw.cam.ac.uk/ipreg. The cookie name and
domain name differ.
Jackdaw has a notion of authentication realms. The cookie management
page on Jackdaw allows you
to manage cookies in all realms. Old Jackdaw API cookies are in the
ipreg realm, and new API cookies are in the ipreg-v3 realm.
The ipreg v3 cookie management page
only deals with ipreg-v3 cookies.