top of page
Search

The Secret Chest API

We believe that the world is just a collection of not-yet-wired-together API endpoints. There is power and versatility in well constructed, well documented APIs, and the ideas that users of multiple products come up with to link those products. The developers could never have thought of all the stuff the users do - which is why we take an API-first mentality. That means we build endpoints and THEN we build our apps and UI around those.


One of the most useful things we do for ourselves is document the API. So we kinda' guessed that users would love access to that as well. The API documentation is buit on a standard swagger template, so available at https://service.secretchest.io/api/v1. To access it, users will need a bearer token. To get a bearer token, open the Secret Chest web app at app.secretchest.io and log in. Once authenticated, click on your username in the lower left corner of the screen to open your profile screen. Then click on Generate Token. Now that there's a token, open the API docs.


All of the available endpoints are shown at the API documentation screen.

Click on the Authorize button and provide the bearer token, clicking Authorize once it's pasted in (for extra awesome, auto-fill it from Secret Chest).


Click on an endpoint to see available parameters and a what the curl equivilent would be should that command be run from the shell.

The command will also output the response and below, notice any appropriate response codes.


Note: For a more thorough list of standard HTTP response codes, see https://krypted.com/programming-2/http-success-and-error-codes/.


There aren't a ton of parameters for endpoints. That's because we chose to build more endpoints rather than complicate what's in them. We were also intentional with what is available with a standard GET vs a POST - given the secure nature of what we are sending in response to requests and what can be viewed from a ZTNA appliance, etc. For the most part, endpoints (inside the app and for the web app) follow the lower camel case standard (or dromedary case if ya' wanna' get nerdy about it), where the initial word begins with a lowercase letter and each subsequent word begins with an uppercase letter.


It is, again, our goal to expose every single thing that can be done with Secret Chest via an API, and to do so safely (and securely since those aren't exactly synonyms). We've heard some vendors over time who didn't want to open up their APIs because they were afrraid users would break their tools. That's just silly. But it's silly because at the end of the day, we have to protect ourselves from vile acts, whether intentional or no. So we do impose rate limiting. Let us know if you bump up against it and would like us to expand it for a given IP or hostname (e.g. your Lambda or GCF URI). We'd be happy to explore why and whether it would be better for us to build a paginated endpoint for a unique need that we hadn't thought of. In fact, to be very clear, we'd be super-stoked to have well informed conversations like that!


Our development team is moving fast, but not breaking things - yet. So notice the V1 (or later according to when looking) in the API documentation. Also notice where in the URL that V1 is. We are versioning the API globally for now. Each is a micro-service so we may move to per-endpoint versioning in the future. If you have opinions, let us know. If we haven't been clear about this, we love to have our assumptions and decisions challenged by smart conversation and well thought out cases (or even not-well thought out cases so we can make cases well thought out together)!

36 views0 comments

Recent Posts

See All

Comments


bottom of page