Projects API Documentation - Version 1

Authentication

Details on how authentication is managed, transmitted and enforced throughout the API.

User accounts

A User represents a person or entity for the purposes of authentication and authorisation.

Within this API only authentication is used to restrict access to privileged information or abilities provided by the API.

See the User resource document for details of what a User resource consists of.

The list of valid Users is controlled by the API Maintainer, they should be contacted to:

• Create or delete user accounts
• Modify user information
• Modify user passwords (including password resets)

See the project administration document for details on the API Maintainer.

Note: Password resets will be delegated to users (for their own password) in future versions of the API.

Tokens

Tokens are used as a safe way to transmit your identity (user account) without exposing your user credentials.

As documented further in the Token resource document, this API uses the JSON Web Token standard for tokens.

This document also describes what a Token consists of and its associated methods (i.e. for issuing and invalidating tokens).

Token expiry

Tokens contain a number of claims [1], one of which determines when the token will naturally expire. This occurs 1 hour from issuance.

Note: Expired tokens cannot be extended, you must request a new token.

Should you need to invalidate a token before its natural expiry, you can “blacklist” it to invalidate it immediately.

This is achieved using the [DELETE]/tokens method of the Token resource.

Note: Blacklisted tokens cannot be “un-blacklisted”, you must request a new token.

[1] This is a technical term defined with the JWT spec

Resource method trait

This trait requires that a request contains a valid authentication token, specified within the Authorisation header of a request.

Headers

Example request

URL: N/A

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

Headers

Body

None.

Example response (200 OK)

Headers (Redundant headers removed)

None.

Body

None.

Example response (500 Internal Server Error - unknown_authentication_token_fault)

Headers (Redundant headers removed)

None.

Body

{
    "errors": [
        {
            "details": {
                "token_error": [
                    "There is something wrong with the token authentication."
                ]
            },
            "resolution": "Try again or get a new token. If needed contact the API maintainer for assistance.",
            "resolutionURLs": [
                "mailto:basweb@bas.ac.uk"
            ],
            "type": "unknown_authentication_token_fault"
        }
    ]
}

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

Example response (401 Unauthorized - missing_authentication_token)

Headers (Redundant headers removed)

None.

Body

{
    "errors": [
        {
            "details": {
                "token_error": [
                    "No authentication token was given and no authentication session exists."
                ]
            },
            "resolution": "Include a token in the 'authorization' header, using the bearer scheme (i.e. 'Authoization: Bearer [token]'.",
            "resolutionURLs": [
                "mailto:basweb@bas.ac.uk"
            ],
            "type": "missing_authentication_token"
        }
    ]
}

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

Example response (400 Bad Request - invalid_authentication_token)

Headers (Redundant headers removed)

None.

Body

{
    "errors": [
        {
            "details": {
                "token_error": [
                    "The authentication token given is not valid or is malformed."
                ]
            },
            "resolution": "Check the token you have provided is complete, or get a new token.",
            "resolutionURLs": [
                "mailto:basweb@bas.ac.uk"
            ],
            "type": "invalid_authentication_token"
        }
    ]
}

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

Example response (404 Not Found - authentication_token_unknown_subject)

Headers (Redundant headers removed)

None.

Body

{
    "errors": [
        {
            "details": {
                "token_error": [
                    "The subject for the authentication token is unknown."
                ]
            },
            "resolution": "Ensure your user account is still active or contact the maintainer of this API for assistance.",
            "resolutionURLs": [
                "mailto:basweb@bas.ac.uk"
            ],
            "type": "authentication_token_unknown_subject"
        }
    ]
}

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)

None.

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.

Example response (401 Unauthorized - blacklisted_authentication_token)

Headers (Redundant headers removed)

None.

Body

{
    "errors": [
        {
            "details": {
                "token_error": [
                    "Authentication token has been blacklisted and can no longer be used."
                ]
            },
            "resolution": "Get a new token by re-authenticating.",
            "resolutionURLs": [
                "mailto:basweb@bas.ac.uk"
            ],
            "type": "blacklisted_authentication_token"
        }
    ]
}

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

Example response (401 Unauthorized - authentication_failure)

Headers (Redundant headers removed)

None.

Body

{
    "errors": [
        {
            "details": {
                "authentication_error": [
                    "Ensure your credentials are correct and that your user account is still active, or contact the maintainer of this API for assistance."
                ]
            },
            "type": "authentication_failure"
        }
    ]
}

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.