HTTP API

Quick Reference

Resource Operation Description
  GET /check Validates a token
Public Key GET /pubkey Returns the public key, if applicable
Refresh Token GET /refresh_token get a refresh token
  DELETE /refresh_token delete a refresh token
Token GET /token get a token
User POST /user Create a new user
  PATCH /user Changes a users password
  GET /user If authentication provided get token JSON payload
  DELETE /user Delete a user
Version GET /version Return the version number of the API

Authentication

Authentication is provided to this API via supplying a JWT.

This JWT can be provided in one of the following ways:

  • Via the header, in the Authorization key
  • As a form encoded argument as the value associated with the key access_token
  • In the query string as the value associated with the key access_token

Each endpoint below specifies one of the following authentication requirements

  • No Authentication: No authentication is required.
  • Authentication Optional: Authentication may be provided - the endpoint may perform differently when authentication is provided.
  • Authentication Required: Authentication must be provided for the endpoint to function
  • Password Authentication Required: Authentication must be provided, and the provided token must have been generated in response to a username/password based login, rather than a refresh token based login.

Providing Arguments

All endpoints of this API utilize a flask_restful.reqparse.RequestParser instance to obtain arguments. Thus, values may be provided via any method which populates either flask.Request.json or flask.Request.values with the appropriate key.

The following documentation documents these keys and values as if they are provided via the JSON body of a request.

Endpoint Documentation

GET /refresh_token

Get a refresh token

Returns an encoded token in plaintext

Authentication: Password Authentication Required

Status Codes:
DELETE /refresh_token

Delete a refresh token

Authentication: Authentication Required

Status Codes:
GET /version

Authentication: No Authentication

Return the version number of the API

Response JSON Object:
 
  • version (string) – The version number of the API
Status Codes:
GET /pubkey

Authentication: No Authentication

Returns the public key as plaintext, if applicable.

Status Codes:
  • 200 OK – No error
  • 404 Not Found – A symmetric algorithm is in use, there is no public key
GET /token

Authentication: No Authentication

Get a token

Returns an encoded token in plaintext

Request JSON Object:
 
  • user (str) – The username to authenticate as, or an encoded refresh token
  • pass (str) – The password for the user, if not utilizing a refresh token
Status Codes:
GET /check

Authentication: No Authentication

Validates a token

If the token is valid, returns the token’s JSON payload

Request JSON Object:
 
  • access_token (str) – The token to check
Response JSON Object:
 

The token payload
Status Codes:
POST /user

Authentication: No Authentication

Create a new user

Request JSON Object:
 
  • user (str) – The username of the user to create
  • pass (str) – The password for the new user
Status Codes:
PATCH /user

Authentication: Password Authentication Required

Changes the authenticated users password.

Request JSON Object:
 
  • pass (str) – The string to change the password to
Status Codes:
GET /user

Authentication: Authentication Optional

If authentication is provided return the token’s JSON payload, otherwise returns an empty response with status code 204.

Response JSON Object:
 

The token payload
Status Codes:
DELETE /user

Authentication: Password Authentication Required

Delete the user

Status Codes: