HTTP API - Authorization

access to the ditto http api is controlled through an authorization bearer http header to authenticate and gain access to the big peer, use a static api key api key accessible from the portal, the api key is a straightforward implementation for authenticating your data product's digital identity with the big peer for authorization the api key is a broad, long lived http api key that, once generated, remains valid for a maximum of one year https //legacydocs ditto live/http/installation#api key security overview ditto implements strong security practices for generating and handling api keys the api key is made up of a combination of random and fixed elements randomly generated prefix fixed prefix randomly generated suffix once received, the big peer performs a hashing process on the suffix element before securely storing the api key creating and saving api keys to generate and retrieve the api key you'll include in your request header, from the portal, do the following you need elevated access permissions to create and save api keys you can perform this action only if your assigned role has the access api keys setting enabled in the portal under settings > roles (see docid\ tfeyusg0hughfbfxvie81 ) log in to the https //portal ditto live/ > click apps > and then select your app from the list click auth , and then click new api key from the lower right corner complete the key configuration form for api key description , enter a description of the key's intended use for api key expiration , if you want to adjust the default date that appears, click the date and then select the date you want from the calendar picker for read permissions , select the option you want to set for read permissions for write permissions , select the option you want to set for write permissions for more information about custom access rules, see /#setting up custom permissions , as follows click create api key from the api key created dialog box copy your api key and save it in a safe location once saved, click i have saved my api key , and then click done setting up custom permissions if you want to scope access to a particular collections or document ids, set up custom access rules for read permissions or write permissions select custom access rules for the operation type you want to set up to scope by collection, enter the collection name to scope by a specific document, from queries , enter your query expression currently, you can only set permission queries on the id field; however, ditto is actively developing a solution for setting queries by mutable fields if invoking the findbyid method, instead of using id , pass the document id as id to add an additional rule, click add query rule and then repeat step 2 and 3 including the api key once you've retrieved your api key, you can make requests to the big peer by including your key in the authorization bearer http header of each of your requests, as demonstrated in the following post request curl curl location request post 'https //{your app id} cloud ditto live/api/v4/store/write' \\ \ header 'authorization bearer {your api key}' \\ \ header 'content type application/json' \\ \ data raw '{ "commands" \[{ "method" "upsert", "collection" "people", "value" { "name" "susan", "age" 31 } }] }' errors most http api errors are indicated with an http status code and a json response body containing an object with a single "error" key in some cases such as a bad gateway or request timeout only a plain text error or {"message" "request timeout"} json object is returned if you receive a json response containing an error field name, its associated field value may be any of the following value description error code the http status code for error message a short description of the error error data an optional object which contains further elaboration about the error transactions each write request — either a post or delete request — to the http api represents a distinct transaction; and each transaction may consist of a single operation or multiple operations if a request to insert an event successfully executes on the big peer, the server includes a transaction id in its response you can then include that id in subsequent get requests to ensure you're accessing only the most up to date and accurate information for that particular event for more information, see /#transaction ids , as follows transaction ids when retrieving events associated with a specific transaction, ensure data consistency by referencing its unique id in your get request by including the transaction id, you ensure that you're working with the most up to date and accurate information by instructing ditto to wait until the events related to that transaction have been fully processed and replicated across the entire mesh before being fetched if you do not supply the transaction id in your request, ditto defaults to using the most recent version of the transaction that is common to all ditto nodes transaction ids instruct the big peer on the order in which transactions should be applied for more information, see the platform manual > docid 2felxg8g6acwurcgp hhk specifying transactions by id when making a get request to find a specific event, instruct ditto to wait until the associated transaction has been fully applied across the entire mesh network before accessing it this ensures that you're working with the most up to date and accurate information to specify a transaction by its associated id, in your get request to the find url endpoint, include the optional x ditto txn id header set to the value of the transaction id for example, a returned transaction id of 14 if the version of the data being requested is not yet available on the server, an error will be included in the response curl curl x get 'https //{app id} cloud ditto live/api/v4/store/find' \\ \ header 'content type application/json' \\ \ header 'authorization bearer $api key' \\ \ header 'x ditto txn id 17'