Authentication REST API documentation

[svicknesh]

I'd like to request a documentation update on how to perform authentication using the REST API, without using the JS client library. I apologize if it already exists and I just missed it, however, I couldn't find it.

Another request is to have a section in the documentation clearly for listing the REST API endpoints for easier reference. Initially I couldn't find the endpoints until I re-read the records section and it was located towards the middle amidst some other information. Alternatively, having a section that appears on the ToC would be helpful as well.

Great job on this tool, and I'm keeping an eye on this as another tool in my repertoire for speedy development. Cheers.

Edit 1

I figured out how to do this

• Using the /_/auth/login page, I figured out the url is <url>/_/api/auth/v1/login with the JSON parameters email and password which will return a JSON response with the auth_token and refresh_token.

{
  "email": "your@email",
  "password": "supersecretpassword"
}

I'm still figuring out how to send the the token with the header, I tried using Authorization but no luck at the moment. Perhaps this can be added to the documentation, until then, hope this helps someone.

Edit 2:

Ok I figured out how to send the token as part of the header by reading the python client library. Use the Authorization header with the value Bearer <auth_token>, note the space between Bearer and <auth_token>.

[ignatz]

I'd like to request a documentation update on how to perform authentication using the REST API, without using the JS client library. I apologize if it already exists and I just missed it, however, I couldn't find it.

No worries, the documentation leaves a lot to be desired. Going forward it will become a bigger priority for me. Your feedback is very much appreciated.

I'm glad you figured it out already but ideally you shouldn't have to. One interim band-aid I can offer: swagger.

cargo run --features="openapi" -- open-api

which will host the swagger ui:

Note, however, that the docs might not be correct given the integration with axum is quite manual and not inferred from the implementation itself.

I'll keep this open as a reminder to improve the docs

---

PS: The authentication tries to follow standard schemes as much as possible: https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#bearer

PPS: For anyone who tries to replicate @svicknesh

$ curl -H 'Content-Type: application/json' \
      -d '{ "email":"admin@localhost","password":"secret"}' \
      -X POST \
      http://localhost:4000/api/auth/v1/login
{"auth_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJFZERTQSJ9.eyJzdWIiOiJBWk9ZWTI0aGRkR0c0QkpzWlZvUUZRPT0iLCJpYXQiOjE3MzczNjUxODksImV4cCI6MTczNzM2NTMwOSwiZW1haWwiOiJhZG1pbkBsb2NhbGhvc3QiLCJjc3JmX3Rva2VuIjoiWHJieFp5SzdqV05KaGVFZUpwUXMifQ.kgognB7reGHsw9QFqKYGFwr9OV_2c82kMnv0KWRZbxgmkXfc6hPUE8TiYBxQwRdtZx6ANcNlOjDb_-5hReExCw","refresh_token":"R4tCdum2gijuuGGtXMZ8q7Cqq3aM1BJo","csrf_token":"XrbxZyK7jWNJheEeJpQs"}

[svicknesh]

Thanks @ignatz for the tip on swagger, that would be very much helpful going forward. Really appreciate the effort you're putting into this. I'm definitely keeping an eye out on this and I hope to help out where possible :-)

[ignatz]

Always happy to help. Just added curl examples to the record API docs, hope that addresses part of your pain points.