Http endpoints for client sdks using api keys vs auth tokens (e.g. clerk)
Hi. We want to allow users to use an sdk (python or typescript) to interact with our convex actions. The provided clients don't seem to work since they require an auth token/configuration that is generally managed by our core auth provider (clerk in our case).
We'd like to set an http header with an api key that is used by our convex code to authenticate and authorize the request. http endpoints do seem to work for this. We've created them, can set a header, and validate that within the http endpoint. This is great, however we do need to then manually create a client that understands the request and response objects. Is there either: 1. a way to automatically generate client (like with openapi) 2. a way to use the provided clients with an api key that is managed within convex (btw, I wish clerk had support for api keys!) Thanks!
We'd like to set an http header with an api key that is used by our convex code to authenticate and authorize the request. http endpoints do seem to work for this. We've created them, can set a header, and validate that within the http endpoint. This is great, however we do need to then manually create a client that understands the request and response objects. Is there either: 1. a way to automatically generate client (like with openapi) 2. a way to use the provided clients with an api key that is managed within convex (btw, I wish clerk had support for api keys!) Thanks!
6 Replies
cc. @ballingt and @Michal Srb who might be best suited to answer
But just so we get a bit of clarity on your use case: You are building a dev tool on top of Convex where your customers are going to be using an SDK to interact with your service?
thanks, correct.
Glad HTTP endpoints are working for you here, providing an API to users is a case we were thinking about for HTTP endpoints. In terms of generating clients, you have a lot of freedom with HTTP endpoints to e.g. do routing dynamically, so you could use another tool to make writing them easier— see https://stack.convex.dev/hono-with-convex.
For 1), I see https://elysiajs.com/ has support for OpenAPI baked in, but I haven't heard from anyone who's tried using it yet in Convex (we may not support it yet). For 2), this would absolutely work: you could have users use the official Convex Python or JS HTTP client by requiring an apiKey argument in the actions/mutations/queries that you want to expose to users, and checking that API key on the first line of the functions you expose. Check out https://stack.convex.dev/wrappers-as-middleware-zod-validation for code reuse patterns to standardize this.
However if your users use Convex clients, they won't get the TypeScript support / autocompletion they would if you wrote your own client. If I were doing this I would write my own client library that wrapped the httpClient in JS or the Python client so that I could give good docstrings, type support etc. for my users.
(I'd love to hear more about your use case to understand more)
thanks. will check out elysia. For 2) we'd much prefer to use a header since that's generally best practices from a security standpoint (did consider passing the api key as an argument). Yea are going down the road of writing our own client. was just hoping for some faster ways to get this done!
Gotcha, yeah if your requirements are to use a header for the api key then you'll need to use HTTP endpoints here. (in which case you won't be able to use official Convex clients for your users)
I'd love to hear if Elysia works, but it would probably take some finagling to be the first to use it on Convex.
The most valuable thing IMO about https://stack.convex.dev/hono-with-convex is seeing that it's very flexible, whether you use Hono or not
If the goal is to get a client and API done quickly on Convex I think writing the client from scratch (which is just making HTTP calls, IME tools that consume OpenAPI specs to generate clients are about as much work until you're generating clients for larger APIs) is your best bet, and then refactoring to make it more maintainable with e.g. OpenAPI later if you want to spend more eng effort on it.
I just heard from a colleague that they briefly tried Elysia that it was going to take some work to get running in the Convex JavaScript runtime, so I wouldn't bet on that for implementation speed.
ok, thanks for the update on Elysia