Authentication

PAD-as-a-Service API uses API keys to authenticate users. All API keys have the prefix pad. Each API key identifies a role in a particular instance. There are 6 roles:

• Operator

• Encryptor

• Decryptor

• Trustee

• Validator

• Auditor

For example, a trustee referencing 3 different instances should have at least 3 different Trustee API keys for each instance. He cannot access some of the endpoints disallowed for a Trustee role (e.g. uploading an encryption).

Using an API key

API keys should be provided in the request header X-API-KEY field. Making a request missing an API key or with an invalid API key will get a 401 Unauthorized response.

Access control list

URI	HTTP Method	Operator	Encryptor	Decryptor	Trustee	Auditor	Validator
/PADs	POST	✔️
/all-trustees	GET	✔️	✔️	✔️	✔️	✔️	✔️
/all-trustees/:trusteeId	GET	✔️	✔️	✔️	✔️	✔️	✔️
/all-validators	GET	✔️	✔️	✔️	✔️	✔️	✔️
/all-validators/:validatorId	GET	✔️	✔️	✔️	✔️	✔️	✔️
/metadata	GET	✔️	✔️	✔️	✔️	✔️	✔️
/encryptions	POST	✔️	✔️
/encryptions	PUT	✔️	✔️
/encryptions/:tokenHash/status	GET	✔️	✔️	✔️	✔️	✔️
/encryptions/:tokenHash/ciphertext	GET	✔️	✔️	✔️
/encryptions/:tokenHash/encrypted-trustee-shares/:trusteeId	GET	✔️		✔️	✔️
/encryptions/:tokenHash/hashed-trustee-shares	GET	✔️	✔️	✔️	✔️	✔️
/encryptions/:tokenHash/encrypted-validator-shares/:validatorId	GET	✔️		✔️	✔️
/data-requests	POST	✔️	✔️
/data-requests	GET	✔️		✔️	✔️	✔️
/data-requests/:token/trustee-responses	POST	✔️		✔️
/data-requests/:token/trustee-responses	GET	✔️	✔️	✔️	✔️
/data-requests/:token/validator-responses	POST	✔️			✔️
/data-requests/:token/validator-responses	GET	✔️	✔️	✔️
/trustee-attestations/:trusteeId	PUT	✔️		✔️
/trustee-attestations/:trusteeId	GET	✔️	✔️	✔️	✔️	✔️	✔️
/digest	GET	✔️	✔️	✔️	✔️	✔️	✔️
/ledger	GET	✔️	✔️	✔️	✔️	✔️	✔️

Rate limiting

We have 2 rate limiting policies: IP + API_key and API_key. Both have a limit of 100 requests per minute. In the IP + API_key policy, if an invalid API key is provided, only the IP is recorded usage of the API. Because of the API_key policy, distinct users of the same role of an instance should use different API keys. For example, Trustee-1 and Trustee-2 who both reference the same instance could use the same API key for serving the instance properly, but this would trigger rate limiting for the API key because the trustees are sharing quotas.

https

All requests should be made with https protocol. Requests made with http protocol will get a 301 Moved Permanantly response directed to https.