People API Documentation - Version 1

Resources - Token (Tokens)

Tokens represent a valid user for a specific period of time for the purposes of authentication.

Resource model

Name Property Name Data Type Optional Description
Token token String No A JSON Web Token [1]

[1] The token property consists of a JSON Web Token which has a standardised structure described here.

Example (JSON)

{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC9ic2x3ZWItZGVuaXplbnMtZGV2LXdlYjFcL2FwaVwvdjFcL3Rva2VucyIsInN1YiI6MSwiaWF0IjoxNDIxMTQ3MTUzLCJleHAiOjE0MjExNTA3NTN9.LIlwJ9IXwMxjh8dxkIw9XbvwWz1juFq8f7pE0dC7Gbc"
}

Resource methods

[POST]/tokens

Issues a new token to a valid user.

Traits
Trait Enabled
Authenticated No
Parameters

None.

Options
Name Field Name Data Type Valid Value(s) Description
Username username String A valid user’s username -
Password password String A valid user’s password -
Example request

URL: https://api.bas.ac.uk/people/v1/tokens

Headers
Key Value
Content-Type application/json
Accept application/json
Body (Raw)
{
  "username": "conwat",
  "password": "password"
}

Note: Interactive examples for this method may be covered in the examples document.

Example response (200 OK)
Headers (Redundant headers removed)
Key Value
Content-Type application/json
Body (JSON)
{
    "notices": [
        {
            "type": "token_generated",
            "details": {
                "expiry": {
                    "expires": 1421150753,
                    "message": "This token will expire at: 2015-01-13 12:05:53, at which point you will need to request a new token."
                }
            }
        }
    ],
    "data": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC9ic2x3ZWItZGVuaXplbnMtZGV2LXdlYjFcL2FwaVwvdjFcL3Rva2VucyIsInN1YiI6MSwiaWF0IjoxNDIxMTQ3MTUzLCJleHAiOjE0MjExNTA3NTN9.LIlwJ9IXwMxjh8dxkIw9XbvwWz1juFq8f7pE0dC7Gbc"
    }
}

[DELETE]/tokens

Manually invalidate a currently valid token before it invalidates naturally.

Traits
Trait Enabled
Authenticated Yes
Parameters

None.

Options

None.

Notes

“Natural” invalidation refers to how tokens will automatically be considered invalid when they reach their expiration date.

See the authentication document for further information on this concept.

Example request

URL: https://api.bas.ac.uk/people/v1/tokens (example)

Headers (Redundant headers removed)
Key Value
Content-Type application/json
Body

None.

Note: Interactive examples for this method may be covered in the examples document.

Example response (200 OK)
Headers (Redundant headers removed)
Key Value
Content-Type application/json
Body
{
    "notices": [
        {
            "type": "token_blacklisted",
            "details": {
                "token_blacklist": {
                    "message": "This token is now blacklisted and will be refused if used again."
                }
            }
        }
    ]
}
Example response (500 Internal Server Error - unknown_blacklist_fault)
Headers (Redundant headers removed)
Key Value
Content-Type application/json
Body
{
    "errors": [
        {
            "resolution": "Try again, or wait for the token to expire naturally. If needed, contact the API maintainer for assistance.",
            "resolutionURLs": [
                "mailto:basweb@bas.ac.uk"
            ],
            "type": "unknown_blacklist_fault"
        }
    ]
}

Note: The format of this error will change in future API versions (to standardise against the json:api spec.

Example response (401 Unauthorized - expired_authentication_token)
Headers (Redundant headers removed)
Key Value
Content-Type application/json
Body
{
    "errors": [
        {
            "details": {
                "token_error": [
                    "The authentication token given has expired and is no longer valid."
                ]
            },
            "resolution": "Get a new token by re-authenticating.",
            "resolutionURLs": [
                "mailto:basweb@bas.ac.uk"
            ],
            "type": "expired_authentication_token"
        }
    ]
}

Note: The format of this error will change in future API versions (to standardise against the json:api spec.

This information may be out of date whilst this website is being redeveloped. Until then, if you have any problems using an API documented here, please contact the relevant project maintainer.