Authentication API

Owned by Former user (Deleted)
Last updated: Jun 02, 2016
1 min read

NOTE This requires a user to be part of the tDAR API Group. Please contact Digital Antiquity staff (info@digitalantiquity.org) to be added to this group.

 

tDAR maintains an XML API for authentication. Prior to using this API, please contact a tDAR staff member (comments@tdar.org) to request access to this API.

Login:

Login Request
URL : http://core.tdar.org/api/login
Method: POST

userLogin.loginUsername

ParameterOptionalNote
userLogin.loginUsernamenoYour Username
userLogin.loginPasswordnoYour password

Login Response

The following parameters will be available in the response:

Parameters:

  • status : Whether the request was successful or not. Either "success" or "error."
  • username: The username specified
  • message: an error message if specified
  • apiToken: the API Token to be used (only specified on a valid authentication)
  • apiTokenName: the parameter name to be used when sending future requests

Examples:

Failed Login Request:

Failed Request
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<tdar:resultContainer xsi:schemaLocation="http://localhost:8180/schema/current schema.xsd" xmlns:tdar="http://www.tdar.org/namespace" xmlns:ns3="http://archaeologydataservice.ac.uk/tag/schema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <tdar:errors>invalid user request, please request API Access</tdar:errors>
    <tdar:statusCode>400</tdar:statusCode>
</tdar:resultContainer>

Successful Login Request:

Successful Login Request
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<tdar:resultContainer username="admin@tdar.org" sessionKeyName="session.tokenkey" apiToken="FcaZZi8ODVC6DUiou02sJQ00" xsi:schemaLocation="http://localhost:8180/schema/current schema.xsd" xmlns:tdar="http://www.tdar.org/namespace" xmlns:ns3="http://archaeologydataservice.ac.uk/tag/schema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <tdar:message>Please review the Terms of Use at http://www.tdar.org/about/policies/terms-of-use/ </tdar:message>
    <tdar:statusCode>200</tdar:statusCode>
</tdar:resultContainer>
Using the Authentication Key

Once you've successfully authenticated, there are two ways to work with tDAR with the key.  First, if the scripting or application language your using supports cookies, a successful authentication includes a session-based authentication cookie which can be used for subsequent tasks.  Alternately, you may include apiTokenKeyName  as a parameterName and apiToken as the associated value in any request and receive an authenticated response.

e.g. if the apiTokenKeyName was set to token and the apiToken was set to letMeIn an authenticated RSS request could be made via http://core.tdar.org/search/rss?token=letMeIn.

Logout

URL : http://core.tdar.org/api/logout
Method: POST

Parameters: None

To logout, simple make a POST request to http://core.tdar.org/api/logout with no parameters.