POST authentication api

Miscellaneous authentication operations

These are all performed by means of a POST to the admin-api base URL for a site. Different values of the "operation" field determine the function to be performed.

Verify login credentials and get account information

The login operation validates a username and password with Tizra. Returns success/failure, and a list of Tizra Licenses that are currently active for that account. A login request might look like this:

{
        "operation": "login",
        "user-name": "account name",
        "password": "something"
}

Normal operations give the following HTTP statuses:

• 403 Authentication failed. Bad account or credentials supplied. The login has failed. We do not reveal further detail to make guessing accounts harder for attackers.
• 200 Success The login has succeeded. The resulting record has the following fields:
  • status duplicates the HTTP status (as in all Tizra API operations) and may be easier to access for some clients.
  • message contains the success or error message.
  • user contains a user record for the logged in user, this includes any Tizra properties and tags associated with the user.
  • licenses
  • location this duplicates the Location header, and contains a URL where the account data record is accessible for update in the admin UI.

A complete result might look like this:

{
    "licenses": [
        {
            "active": true, 
            "controlled": "9udm", 
            "props": {
                "testProp": ""
            }, 
            "terms": {
                "concurrencies": 2, 
                "duration": "perpetual", 
                "excluded-views": [
                    "sourceDownload"
                ], 
                "is-expired": false, 
                "meta-type-restriction": "Book"
            }
        }, 
        {
            "active": true, 
            "controlled": "262i", 
            "props": {
                "redemption-code": "9e1ebe228d8026d0", 
                "redemption-date": "Thu Sep 11 20:42:05 EDT 2014"
            }, 
            "terms": {
                "duration": "perpetual", 
                "excluded-views": [
                    "sourceDownload"
                ], 
                "is-expired": false
            }
        }
    ], 
    "location": "/admin-api/9p2/objects/pfss", 
    "message": "logged in", 
    "status": 200, 
    "user": {
        "email": "example@tizra.com", 
        "has-unpublished-changes": true, 
        "is-free": false, 
        "live-date": "", 
        "management-url": "/admin-api/9p2/objects/pfss", 
        "meta-type": "UserData", 
        "name": null, 
        "props": {
            "AdminTags": [
                "tizra.com", 
                "the gorgons gaze", 
                "ha"
            ], 
            "City": [
                "Providence"
            ], 
            "CountryCode": "PL", 
            "Email": "", 
            "EmailAddress": "", 
            "FirstName": "david", 
            "JobFunction": "232", 
            "LastName": "testo", 
            "Province": [], 
            "SchoolDistrictOrg": "", 
            "State": "", 
            "Street": "9 Catalpa Road", 
            "Street2": "", 
            "Tizra-customUrl": "", 
            "Zip": "02906"
        }, 
        "published-live": true, 
        "published-staging": true, 
        "sources": [], 
        "staging-date": "", 
        "tizra-id": "pfss", 
        "url-id": "pfss", 
        "user-status": 1, 
        "user-status-description": "Active"
    }
}

The format of licenses is described in the License Management API documentation.

Change account password

The change-password operation can update an account's password.

Tizra prefers email addresses as account names. Tizra does not store passwords in plain text, and there is therefore no way to find a lost password. This function requires authentication as an administrator via the API token, so it cannot be used from a User's browser, or over a non-secure connection. Use should always be over an HTTPs connection, from a platform whose security is adequate to protect an administrative password.

https://secure.agilepdf.com/admin-api/<site-id>/

{
        "operation": "change-password",
        "user-name": "account name",
        "password": "something"
}

Normal operations give the following HTTP statuses:

• 403 Nonexistent account Update attempt failed.
• 200 Success Update succeeded.