NAV
http

Tigrosa 2.0.0

Apex

/ GET

Response 200

HTTP/1.1 200 OK
content-type: application/json
{
  "tigrosa": {
    "t_now": "2020-11-23T19:45:53.105606393Z",
    "version": "0.0.0"
  }
}

Read the API apex, returning metadata about the API and its status. This route is suitable for use as a healthcheck, indicating whether the API is available and healthy. Calling the route operates as a shallow healthcheck; periodically, however, a deep healthcheck is performed, the time of which is logged in t_now.

Response Parameters

Parameter Type Description
tigrosa.t_now string time of last deep healthcheck
tigrosa.version string version of API
(might be extended by upstream)

Organisation

/org POST

Request

POST /org HTTP/1.1
content-type: application/json
{}

Response 201

HTTP/1.1 201 Created
location: /org/4d164ed8-9ab7-4b30-9015-2ca0f6d9295e
content-type: application/json
{
  "href": "/org/4d164ed8-9ab7-4b30-9015-2ca0f6d9295e",
  "locked": false
}

Create an Organisation.

Request Parameters

Parameter Type Description
locked boolean? locked, blocking access

Response Parameters

Response Parameters are as for /org/:org_id GET.

/org GET

Response 200

HTTP/1.1 200 OK
link: </org>; rel="first", </org?_next=2020-11-23T17:29:12.76984Z>; rel="next", </org?_prev=2020-11-23T17:29:12.813139Z>; rel="prev"
content-type: application/json
[
  {
    "href": "/org/af9d1bed-dbda-49c4-9c7b-881cdae4ab6a",
    "locked": false
  },
  {
    "href": "/org/26b201dd-5011-48d2-8edf-010eb0e78c09",
    "locked": false
  }
]

List Organisations.

Response Parameters

Response Parameters are as for /org/:org_id GET.

/org/:org_id GET

Response 200

HTTP/1.1 200 OK
content-type: application/json
{
  "href": "/org/903062a6-cf39-4d51-86de-5f1e23919726",
  "locked": false
}

Read an Organisation.

Response Parameters

Parameter Type Description
href string Href
locked boolean locked, blocking access
(might be extended by upstream)

/org/:org_id PATCH

Request

Response 200

Update an Organisation.

Request Parameters

Request Parameters are as for /org POST.

Response Parameters

Response Parameters are as for /org/:org_id GET.

/org/:org_id DELETE

Response 204

HTTP/1.1 204 No Content
content-type: text/plain; charset=utf-8

Delete an Organisation.

Organisation-User

/org/:org_id/usr/:usr_id PUT

Request

PUT /org/69263960-47bf-461a-8666-3e65c79c7537/usr/32811990-41f6-40b3-9311-534dbd0f5a24 HTTP/1.1
content-type: application/json
{}

Response 201

HTTP/1.1 201 Created
location: /org/69263960-47bf-461a-8666-3e65c79c7537/usr/32811990-41f6-40b3-9311-534dbd0f5a24
content-type: application/json
{
  "href": "/org/69263960-47bf-461a-8666-3e65c79c7537/usr/32811990-41f6-40b3-9311-534dbd0f5a24",
  "level": "member",
  "org": {
    "href": "/org/69263960-47bf-461a-8666-3e65c79c7537",
    "locked": false
  },
  "usr": {
    "href": "/usr/32811990-41f6-40b3-9311-534dbd0f5a24",
    "locked": false,
    "realm": "private"
  }
}

Associate a User with an Organisation.

Request Parameters

There are no Request Parameters.

Response Parameters

Response Parameters are as for /org/:org_id/usr/:usr_id GET.

/org/:org_id/usr/:usr_id GET

Response 200

HTTP/1.1 200 OK
content-type: application/json
{
  "href": "/org/a4da0df5-1483-41bd-a5cc-4d10b2b09c9c/usr/8a558297-1841-4bda-b663-4001ae5777b5",
  "level": "member",
  "org": {
    "href": "/org/a4da0df5-1483-41bd-a5cc-4d10b2b09c9c",
    "locked": false
  },
  "usr": {
    "href": "/usr/8a558297-1841-4bda-b663-4001ae5777b5",
    "locked": false,
    "realm": "private"
  }
}

Read an Organisation-User association.

Response Parameters

Parameter Type Description
href string Href
level string resource membership level, for X-Tigrosa-Resource
org object Organisation
usr object User

/org/:org_id/usr/:usr_id DELETE

Response 204

HTTP/1.1 204 No Content

Disassociate a User from an Organisation.

User

/usr POST

Request

POST /usr HTTP/1.1
content-type: application/json
{}

Response 201

HTTP/1.1 201 Created
location: /usr/df393f39-5d5b-4749-8cae-6a12741b3302
content-type: application/json
{
  "href": "/usr/df393f39-5d5b-4749-8cae-6a12741b3302",
  "locked": false,
  "realm": "private"
}

Create a User.

Request Parameters

Parameter Type Description
locked boolean? locked, blocking access

Response Parameters

Response Parameters are as for /usr/:usr_id GET.

/usr GET

Response 200

HTTP/1.1 200 OK
link: </usr>; rel="first", </usr?_next=2020-11-23T17:29:39.775301Z>; rel="next", </usr?_prev=2020-11-23T17:29:39.89566Z>; rel="prev"
content-type: application/json
[
  {
    "href": "/usr/f133b208-0b92-4b2d-9a83-3cc64c4769a0",
    "locked": false,
    "realm": "private"
  },
  {
    "href": "/usr/a45d108d-68cd-4a79-b569-e3008e4bf9bf",
    "locked": false,
    "realm": "private"
  }
]

List Users.

Response Parameters

Response Parameters are as for /usr/:usr_id GET.

/usr/:usr_id GET

Response 200

HTTP/1.1 200 OK
content-type: application/json
{
  "href": "/usr/b3a943f0-1268-4b22-bedd-ec60ce45c657",
  "locked": false,
  "realm": "private"
}

Read a User.

Response Parameters

Parameter Type Description
href string Href
locked boolean locked, blocking access
realm string global access realm, for X-Tigrosa-Realm

/usr/:usr_id PATCH

Request

Response 200

Update a User.

Request Parameters

Request Parameters are as for /usr POST.

Response Parameters

Response Parameters are as for /usr/:usr_id GET.

/usr/:usr_id DELETE

Response 204

HTTP/1.1 204 No Content

Delete a User.

User-Key

/usr/:usr_id/usr_key POST

Request

POST /usr/5e821a19-5127-49ec-964f-390b523890fb/usr_key HTTP/1.1
content-type: application/json
{
  "rsa_key_pub": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0k55xrE7OiGsN5/axVD2\nftl1A+4o7qfP2ewK57UKUt3O/Qm3P3cprzD9+AC0//6wiw8mn1nhaWc7KtOc6U+t\nxt8GYoIEUVjp3VO0DEt0P29m6ARWY26ZCfyx5SHNgVujq5ysFtjI3oHUWznAthDy\n5dxjKDntFWbBWUGVp78L6LkMjY8d+QNIgc4CuyZYMHYONaqqn9V3mT9HTrQcVn/7\n7vibReZsGE2Tb1PUsmkvfQiOkYQVxax4HGq0RJ7RHCOjoTdzQgkQrPRXCVe3zseh\nyplAYSkAWYGZo4qySjtmX6ICyY2Z2tJmxy9juqxwKSC+rQF0K+EfjR+TKySYhqCT\nuwIDAQAB\n-----END PUBLIC KEY-----\n"
}

Response 201

HTTP/1.1 201 Created
location: /usr_key/6a06b9ee-5e20-4699-9de3-acb3366deab3
content-type: application/json
{
  "href": "/usr_key/6a06b9ee-5e20-4699-9de3-acb3366deab3",
  "rsa_key_pub": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0k55xrE7OiGsN5/axVD2\nftl1A+4o7qfP2ewK57UKUt3O/Qm3P3cprzD9+AC0//6wiw8mn1nhaWc7KtOc6U+t\nxt8GYoIEUVjp3VO0DEt0P29m6ARWY26ZCfyx5SHNgVujq5ysFtjI3oHUWznAthDy\n5dxjKDntFWbBWUGVp78L6LkMjY8d+QNIgc4CuyZYMHYONaqqn9V3mT9HTrQcVn/7\n7vibReZsGE2Tb1PUsmkvfQiOkYQVxax4HGq0RJ7RHCOjoTdzQgkQrPRXCVe3zseh\nyplAYSkAWYGZo4qySjtmX6ICyY2Z2tJmxy9juqxwKSC+rQF0K+EfjR+TKySYhqCT\nuwIDAQAB\n-----END PUBLIC KEY-----\n",
  "usr": {
    "href": "/usr/5e821a19-5127-49ec-964f-390b523890fb",
    "locked": false,
    "realm": "private"
  }
}

Generating a key using OpenSSL

openssl genrsa -out pri.pem 2048
openssl rsa -in pri.pem -outform PEM -pubout -out pub.pem

Create a User-Key.

Request Parameters

Parameter Type Description
rsa_key_pub string RSA public key (PEM)

Response Parameters

Response Parameters are as for /usr_key/:usr_key_id GET.

/usr/:usr_id/usr_key GET

Response 200

HTTP/1.1 200 OK
link: </usr/6abcc387-85bd-455f-9a3c-8c3dad585e18/usr_key>; rel="first", </usr/6abcc387-85bd-455f-9a3c-8c3dad585e18/usr_key?_next=2020-11-23T17:29:21.721489Z>; rel="next", </usr/6abcc387-85bd-455f-9a3c-8c3dad585e18/usr_key?_prev=2020-11-23T17:29:21.893572Z>; rel="prev"
content-type: application/json
[
  {
    "href": "/usr_key/13e6c874-11f1-4fbf-94c8-14078e547005",
    "rsa_key_pub": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArRG7rjFkepQHwHYMppL1\naHVVhoPhym2f49tQFm7SWZshFyDjSOQI9kYT3UKVrhH4acKCvmtBucu/vQ8F/cQN\n1qsYjpp1JxD1PkPb1FeGoZGpwPhC72cYx8EOeXkvvg2DvDWWquyVCh2jSL0sErRH\nbK/tCbH0vjqyVdg6Sv83x1A+aWmMInLdqy4lynmteubuhY9hjkqvfko+GEe/oLS2\nAOg+AqA/aXf4b82lHl9JOgMDLreBgvhsDC+tVox7cC/ViWQnRvtQL/26a8lI5qQf\nEVoFXmtn4U8W5CeQ5uR2pVMissZ3G/kXqRpePX1WI5LrqL+OFqRhCHb2Ikh8PR6L\n6wIDAQAB\n-----END PUBLIC KEY-----\n",
    "usr": {
      "href": "/usr/6abcc387-85bd-455f-9a3c-8c3dad585e18",
      "locked": false,
      "realm": "private"
    }
  },
  {
    "href": "/usr_key/a8d99cdb-73a4-4275-93c0-d1d67e040df6",
    "rsa_key_pub": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAod1E45YMEyV/G7mwPn4C\n+xDj4eXdNIhlYOJ2QfYE7188Uztx5Ry7N5Lsos0Va3qXyACwQinNj33UM8x59Mvc\nS00LA91Wdd1Q/Su39QBDegHBoE407mMvBkEb9nwsiwj00FvIDy5dN7A513UYzN60\nAGGgJG5XzL1vMBySL/8fI0gFw8l1A881OD2OgZzHeQ/2FI6TBrp35ZXX1VNThUpK\nLPZIqN6thCRajP9H9SWzK2zZvMNi7CDvSHwWZG3SLbKj3iwuIWv7d8JKMzInvEAv\n2sV+RHn9MkM8YttF5yf7O26n0nW1AvXl77di7R0mzxMzcjzolBEBoxrJ/qnsECP+\nOwIDAQAB\n-----END PUBLIC KEY-----\n",
    "usr": {
      "href": "/usr/6abcc387-85bd-455f-9a3c-8c3dad585e18",
      "locked": false,
      "realm": "private"
    }
  }
]

List User-Keys.

Response Parameters

Response Parameters are as for /usr_key/:usr_key_id GET.

/usr_key/:usr_key_id GET

Response 200

HTTP/1.1 200 OK
content-type: application/json
{
  "href": "/usr_key/549e09ba-fff6-49ea-ba01-86dd45642c76",
  "rsa_key_pub": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwJFXkg+s0xfc2bgEDAJV\n7myx2YY7y8XvKY/Tn1duT65lBPFFKIa3DYl2XZ66jYm6C4k6wLgSaeZUmCfP472Y\npwVE6rEbNdUDg6pqcWRV1USdHXzDOwvqRVhVedKzi4hZZ4FBlWor2NuXFfvRNUw2\n8z2l/fpvWdMqBM9bPpM9nJRKr0tgcOz77yPGiYFZHqTRFHnR3aOwObSojkmaEday\nxP/PCvxUVC54xamw0Pp1G/CKxsCPEorwFxnSD6FtW2niEjqrDxcMqCaVG3I4d/5t\nkKFQ/ACFHvuCX/SXUQAx8GZwoofVrnipB4Mfop9Z49YphgAM1qmJBCevJnQIa2E+\nEQIDAQAB\n-----END PUBLIC KEY-----\n",
  "usr": {
    "href": "/usr/4b3ddb85-6691-41ac-afcf-f62f5ad71cd5",
    "locked": false,
    "realm": "private"
  }
}

Read a User-Key.

Response Parameters

Parameter Type Description
href string Href
rsa_key_pub string RSA public key (PEM)
usr object User

/usr_key/:usr_key_id DELETE

Response 204

HTTP/1.1 204 No Content

Delete a User-Key.

User-Password

/usr/:usr_id/usr_pwd POST

Request

POST /usr/3fef18bb-fbf8-4257-8cca-f3ffe9191261/usr_pwd HTTP/1.1
content-type: application/json
{}

Response 201

HTTP/1.1 201 Created
location: /usr_pwd/ed9af9bb-cde7-4f43-aa09-ea3411945617
content-type: application/json
{
  "href": "/usr_pwd/ed9af9bb-cde7-4f43-aa09-ea3411945617",
  "pass": "d+q3Ee8QtXMnHjwOeXgMWVp0",
  "usr": {
    "href": "/usr/3fef18bb-fbf8-4257-8cca-f3ffe9191261",
    "locked": false,
    "realm": "private"
  }
}

Create a User-Password.

Request Parameters

There are no Request Parameters.

Response Parameters

Response Parameters are as for /usr_pwd/:usr_pwd_id GET, with the following additions:

Parameter Type Description
pass string generated password

/usr/:usr_id/usr_pwd GET

Response 200

HTTP/1.1 200 OK
link: </usr/6e8a5342-d324-4e71-a4e4-bee5f0247265/usr_pwd>; rel="first", </usr/6e8a5342-d324-4e71-a4e4-bee5f0247265/usr_pwd?_next=2020-11-23T17:29:26.490933Z>; rel="next", </usr/6e8a5342-d324-4e71-a4e4-bee5f0247265/usr_pwd?_prev=2020-11-23T17:29:26.518029Z>; rel="prev"
content-type: application/json
[
  {
    "href": "/usr_pwd/4f236407-0b1c-4556-a8cd-01666cbf8e15",
    "usr": {
      "href": "/usr/6e8a5342-d324-4e71-a4e4-bee5f0247265",
      "locked": false,
      "realm": "private"
    }
  },
  {
    "href": "/usr_pwd/796149f7-6f66-4306-98e1-02e319291ef5",
    "usr": {
      "href": "/usr/6e8a5342-d324-4e71-a4e4-bee5f0247265",
      "locked": false,
      "realm": "private"
    }
  }
]

List User-Passwords.

Response Parameters

Response Parameters are as for /usr_pwd/:usr_pwd_id GET.

/usr_pwd/:usr_pwd_id GET

Response 200

HTTP/1.1 200 OK
content-type: application/json
{
  "href": "/usr_pwd/e3974a01-385d-449b-b35d-b3d6d32d9c81",
  "usr": {
    "href": "/usr/fd86df1a-bbee-41c8-a276-f4b8e4441e09",
    "locked": false,
    "realm": "private"
  }
}

Read a User-Password.

Response Parameters

Parameter Type Description
href string Href
usr object User

/usr_pwd/:usr_pwd_id DELETE

Response 204

HTTP/1.1 204 No Content

Delete a User-Password.

User-Session

/usr/:usr_id/usr_ses GET

Response 200

HTTP/1.1 200 OK
link: </usr/3e704b59-0d6e-46fe-8f28-679318f25500/usr_ses>; rel="first", </usr/3e704b59-0d6e-46fe-8f28-679318f25500/usr_ses?_next=2020-11-23T17:29:31.253483Z>; rel="next", </usr/3e704b59-0d6e-46fe-8f28-679318f25500/usr_ses?_prev=2020-11-23T17:29:31.283477Z>; rel="prev"
content-type: application/json
[
  {
    "href": "/usr_ses/0436d726-f0e5-44a1-a61a-7cf25caeb525",
    "t_exp": "2020-11-23T17:30:31.283477Z",
    "usr": {
      "href": "/usr/3e704b59-0d6e-46fe-8f28-679318f25500",
      "locked": false,
      "realm": "private"
    }
  },
  {
    "href": "/usr_ses/1978820e-63b9-412b-bd46-758baf71cc71",
    "t_exp": "2020-11-23T17:30:31.253483Z",
    "usr": {
      "href": "/usr/3e704b59-0d6e-46fe-8f28-679318f25500",
      "locked": false,
      "realm": "private"
    }
  }
]

List User-Sessions.

Response Parameters

Response Parameters are as for /usr_ses/:usr_ses_id GET.

/usr_ses POST

User-Password approach: Request

{
  "ttl": 60
}

User-Password approach: Response 201

HTTP/1.1 201 Created
location: /usr_ses/ec2be49b-8001-4850-97b2-197e5ffcc1de
content-type: application/json
{
  "href": "/usr_ses/ec2be49b-8001-4850-97b2-197e5ffcc1de",
  "t_exp": "2020-11-23T17:30:33.716364Z",
  "token": "hoDhNFjqlWdrBr9ek1/5VOW8xxl562n3uShlcfDBZGk7",
  "usr": {
    "href": "/usr/2b8ead88-da0f-4072-bc14-cb278715a3f8",
    "locked": false,
    "realm": "private"
  }
}

User-Key approach: Request

{
  "t_ins": "2020-11-23T17:29:33.523752605Z",
  "ttl": 60
}

User-Key approach: Response 201

HTTP/1.1 201 Created
location: /usr_ses/a4a5687c-1745-4aed-8251-1f434457ac9a
content-type: application/json
{
  "href": "/usr_ses/a4a5687c-1745-4aed-8251-1f434457ac9a",
  "t_exp": "2020-11-23T17:30:33.572666Z",
  "token": "cAYOFK4YdDjaYdX+5A0OMTgtXmZCtFX6CB0YDx8FfP+a",
  "usr": {
    "href": "/usr/abe77bee-9acf-43d3-b984-cf2c53b14fba",
    "locked": false,
    "realm": "private"
  }
}

Create a User-Session. Note that this does not live under a User route namespace, since it exceptionally detects and verifies the User based on User-Keys or User-Passwords.

There are two approaches:

Request Parameters

Parameter Type Description
t_ins string current time
ttl number TTL (s); min: 60 (1 m); max: 86400 (1 d)

Response Parameters

Response Parameters are as for /usr_ses/:usr_ses_id GET, with the following additions:

Parameter Type Description
token string token with which to perform other authenticated requests

User-Password approach: Logging in using a password

export ENDPOINT_URL=http://localhost:8000
export USR_HREF=/usr/62cdf0b3-e75d-41c2-be15-0c1d4aab28fd

export DIR=".tigrosa"

export ttl=60
export pass="xHsPGNpU0AbtNiSDUXyRO3og"

# generate create session payload
j=$(cat <<-EOT
    {
      "ttl": $ttl
    }
    EOT
    )
echo "$j" | jq

# POST payload to create session
t=$(
    curl -f -u "$USR_HREF:$pass" -X POST -d "$j" "$ENDPOINT_URL/usr_ses"
)
echo "$t" | jq

User-Key approach: Signing a body using an RSA key

export ENDPOINT_URL=http://localhost:8000
export USR_KEY_HREF=/usr_key/2d5c7fc1-a9dd-4b94-a01a-909f083b1ccb

export DIR=".tigrosa"
export KEY_PRI_PEM="$DIR/pri.pem"
export SES_JSON="$DIR/ses.json"
export SES_JSON_SIG="$DIR/ses.json.sha256.sig.base64"

export ttl=60

# generate create session payload; beware of clock-drift
cat > "$SES_JSON" <<-EOT
    {
      "t_ins": "$(date -Iseconds)",
      "ttl": "$ttl"
    }
    EOT
jq < "$SES_JSON"

# use RSA key to sign a SHA-256 hash of the payload
tr -d '\n' < "$SES_JSON" |
    openssl dgst -sha256 -sign "$KEY_PRI_PEM" |
    base64 -w0 \
    > "$SES_JSON_SIG"

# POST payload to create session
t=$(
    curl -f -u "$USR_KEY_HREF:$(cat "$SES_JSON_SIG")" \
        -X POST -d"@$SES_JSON" "$ENDPOINT_URL/usr_ses"
)
echo "$t" | jq

/usr_ses/:usr_ses_id GET

Response 200

HTTP/1.1 200 OK
content-type: application/json
{
  "href": "/usr_ses/1ae74355-8f67-4e01-a0b3-b8aa96cc21f3",
  "t_exp": "2020-11-23T17:30:36.049119Z",
  "usr": {
    "href": "/usr/df0debbc-9777-4226-93f6-1ab85164285b",
    "locked": false,
    "realm": "private"
  }
}

Read a User-Session.

Response Parameters

Parameter Type Description
href string Href
t_exp string time of token expiry
usr object User

/usr_ses/:usr_ses_id DELETE

Response 204

HTTP/1.1 204 No Content

Delete a User-Session.

Proxy

/* * (PROXY)

Upstream Proxy Request

GET /_xxx HTTP/1.1
Host: test_echo
Content-Length: 0
X-Tigrosa-Realm: private
X-Tigrosa-Resource: </org/632df371-92ec-4314-8a0b-d694b153ce53>; rel="member", </org/65f15819-d935-486c-9a2c-8f4982ee6da9>; rel="member"
Accept-Encoding: gzip

There are usually no Response 404s returned directly by Tigrosa; rather, if a route or method is not matched, it is proxied to the upstream backend, which determines the response and any errors. This is an exceptional collection of routes, giving Tigrosa the flexibility to interface with significantly different upstream programs written in any programming language. As such, Tigrosa is a proxy with specific extra functionality layered in front.

If a route matches something listed for Tigrosa, usually the upstream backend receives no notification of the request. There are some exceptions to this, which are noted under the routes concerned. Similarly, if authentication or authorisation fails for some reason, no request is made to the upstream server. By doing so, Tigrosa can vigorously defend against a variety of attacks, as well as vastly simplifying the authentication and authorisation logic in the upstream backend.

The upstream body need not be JSON (although it usually is); it could be HTML, XML, or simply your favourite picture of a spider. In this regard, Tigrosa acts very similarly to a standard proxy. However, Tigrosa reserves some headers, transmitting them as part of the request; the upstream backend may trust these without verification, and act upon them accordingly. By design, Tigrosa also doesn’t transmit certain information about the original request, including the source IP; in this GDPR-friendly era, this is to discourage upstream applications from attempting to store PII separately to any analysis used for ingress.

Realm

The X-Tigrosa-Realm details the global access realm of your User.

Value Description
public unauthenticated
private authenticated; X-Tigrosa-Resource might contain further context
admin authenticated admin
x-maint system maintenance; used for proxying for upstream referential integrity
(might be extended)

Resource

The X-Tigrosa-Resource details the resource membership level of your User. This is supplied in the same format as a Link header; thus, the same libraries may be used to parse the information. As well as giving the resource HREF, the rel attribute is used to give further information about the access level for that resource.

Value Description
member member of the specified resource
admin admin of the specified resource
(might be extended)