Hutch API Documentation

November 13, 2021 · View on GitHub

Here is the full documentaition of the REST API.

All the endpoints in /apiprefix return data in JWT format. The JWTs are signed using the JWKS specified by the property sign_key in the hutch.config file. The key used to sign every response is the one specified in the user profile or the first key if none is specified.

The response format specified in this document is in JSON to make this document easier to read, but you must assume all responses are in JWT format.

Example of JWT response:

HTTP/1.1 200 OK
Content-Type: application/jwt
Pragma: no-cache
Cache-Control: no-store

eyJpYXQiOjE2MzY2Nzk0MDIsImV4cCI6MTYzNjY4MDAwMiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYiLCJraWQiOiJyc2EifQ.eyJrZXlzIjpbeyJraWQiOiJyc2EiLC[...]PY2lGWTFjVFQwIn1dfQ.Ewrzjss88[...]R-afaT3A

A JWT response will contain the header values iat and exp which should be verified by the client to mitigate replay attacks.

The API prefix is /api by default, so this value will be used in this document, you can change this in the hutch.config file.

Authentication

Authentication is required for all endpoints in the /api prefix, those endpoints rely on a valid bearer access token using the JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens standards, with a valid signature. For all requests, the user identifier used is the sub claim in the access token.

The configuration endpoints /.well-known/hutch-configuration and /jwks don't need authentication.

Hutch configuration

The configuration endpoints /.well-known/hutch-configuration and /jwks are the only one which send response in JSON format by default. If the client adds the header Accept: application/jwt in the request, the response will be in JWT format using the first key of the signing JWKS.

{
  "jwks_uri":                  URL to the Hutch server JWKS, mandatory
  "oidc_server_remote_config": URL to the openid-configuration, optional
  "profile_endpoint":          URL to the profile API, mandatory
  "safe_endpoint":             URL to the safe API, mandatory
  "scope":                     List of scopes required by Hutch separated by spaces, mandatory
}

// Example of JWKS output
{
  "keys": [
    {
      "alg": "RS256",
      "e": "AQAB",
      "kid": "rsa",
      "kty": "RSA",
      "n": "zHpJ7[...]TRaxUQ"
    },
    {
      "alg": "ES256",
      "crv": "P-256",
      "kid": "ecdsa",
      "kty": "EC",
      "x": "MPx0yi[...]yZH1tY",
      "y": "N29F26[...]Y1cTT0"
    }
  ]
}

{
  "last_updated": Epoch time when the profile was last updated, integer
  "message":      Profile fortune message, string
  "name":         Profile user name, string
  "picture":      Profile picture, string
  "sign_kid":     kid of the key used to signe responses, string
}

{
  "name"    : string, max 256 characters
  "fortune" : string, max 512 characters
  "picture" : string, max 16MB characters (mediumblob)
  "sign_kid": string, must match an existing kid in the server JWKS
}

Success response

Code 200

Error Response

Code 400

Error input parameters

Content: json array containing all errors

[ // Array of safe
  {
    "name"         : string, 128 characters max
    "display_name" : string, 512 characters max
    "enc_type"     : string
    "alg_type"     : string
  }
]

{
  "name"         : string, 128 characters max
  "display_name" : string, 512 characters max
  "enc_type"     : string, 128 characters max
  "alg_type"     : string, 128 characters max
}

Error Response

Code 403

Profile not set

Code 404

Safe not found

{
  "name"         : string, 128 characters max, must be unique for the current user
  "display_name" : string, 512 characters max
  "enc_type"     : string, 128 characters max
  "alg_type"     : string, 128 characters max
}

Success response

Code 200

Error Response

Code 403

Profile not set

Code 400

Error input parameters

Content: json array containing all errors

{
  "display_name" : string, 512 characters max
  "enc_type"     : string, 128 characters max
  "alg_type"     : string, 128 characters max
}

Success response

Code 200

Error Response

Code 403

Profile not set

Code 400

Error input parameters

Content: json array containing all errors

Code 404

Safe not found

Code 404

Safe not found

[ // Array of safe keys
  {
    "type"         : string, 128 characters max
    "name"         : string, 128 characters max
    "display_name" : string, 512 characters max
    "data"         : string, 16M characters max
  }
]

{
  "type"         : string, 128 characters max
  "name"         : string, 128 characters max
  "display_name" : string, 512 characters max
  "data"         : string, 16M characters max
}

Error Response

Code 403

Profile not set

Code 404

Safe key not found

{
  "type"         : string, 128 characters max
  "name"         : string, 128 characters max
  "display_name" : string, 512 characters max
  "data"         : string, 16M characters max
}

Success response

Code 200

Error Response

Code 403

Profile not set

Code 400

Error input parameters

Content: json array containing all errors

{
  "type"         : string, 128 characters max
  "display_name" : string, 512 characters max
  "data"         : string, 16M characters max
}

Success response

Code 200

Error Response

Code 403

Profile not set

Code 400

Error input parameters

Content: json array containing all errors

Code 404

Safe key not found

Code 404

Safe key not found

[ // Array of coins
  {
    "name":string, 128 characters max
    "data":string, 16MB max
  }
]

{
  "name":string, 128 characters max
  "data":string, 16MB max
}

Error Response

Code 500

Internal Error

Code 404

Coin not found

{
  "name":string, 128 characters max, must be unique for the current safe
  "data":string, 16MB max
}

Success response

Code 200

Error Response

Code 500

Internal Error

Code 400

Error input parameters

Content: json array containing all errors

@coin_name: Coin name

Data Parameters

{
  "data":string, 16MB max
}

Success response

Code 200

Error Response

Code 500

Internal Error

Code 400

Error input parameters

Content: json array containing all errors

Code 404

Coin not found

@coin_name: Coin name

Success response

Code 200

Error Response

Code 500

Internal Error

Code 404

Coin not found