> For the complete documentation index, see [llms.txt](https://docs.padprotocol.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.padprotocol.org/api_desc/api_auth.md). # 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` | :heavy\_check\_mark: | | | | | | | /all-trustees | `GET` | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | | /all-trustees/:trusteeId | `GET` | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | | /all-validators | `GET` | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | | /all-validators/:validatorId | `GET` | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | | /metadata | `GET` | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | | /encryptions | `POST` | :heavy\_check\_mark: | :heavy\_check\_mark: | | | | | | /encryptions | `PUT` | :heavy\_check\_mark: | :heavy\_check\_mark: | | | | | | /encryptions/:tokenHash/status | `GET` | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | | | /encryptions/:tokenHash/ciphertext | `GET` | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | | | | | /encryptions/:tokenHash/encrypted-trustee-shares/:trusteeId | `GET` | :heavy\_check\_mark: | | :heavy\_check\_mark: | :heavy\_check\_mark: | | | | /encryptions/:tokenHash/hashed-trustee-shares | `GET` | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | | | /encryptions/:tokenHash/encrypted-validator-shares/:validatorId | `GET` | :heavy\_check\_mark: | | :heavy\_check\_mark: | :heavy\_check\_mark: | | | | /data-requests | `POST` | :heavy\_check\_mark: | :heavy\_check\_mark: | | | | | | /data-requests | `GET` | :heavy\_check\_mark: | | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | | | /data-requests/:token/trustee-responses | `POST` | :heavy\_check\_mark: | | :heavy\_check\_mark: | | | | | /data-requests/:token/trustee-responses | `GET` | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | | | | /data-requests/:token/validator-responses | `POST` | :heavy\_check\_mark: | | | :heavy\_check\_mark: | | | | /data-requests/:token/validator-responses | `GET` | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | | | | | /trustee-attestations/:trusteeId | `PUT` | :heavy\_check\_mark: | | :heavy\_check\_mark: | | | | | /trustee-attestations/:trusteeId | `GET` | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | | /digest | `GET` | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | | /ledger | `GET` | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | :heavy\_check\_mark: | ## 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`](https://datatracker.ietf.org/doc/html/rfc7231#section-6.4.2) response directed to https. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.padprotocol.org/api_desc/api_auth.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.