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.

[EMUNES]

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

I wonder where to run the command above to check RESTful APIs. I know it's Rust Cargo command, and I tried running this command in docker container which holds trailbase but it doesn't work without Rust toolchain installed.

[ignatz]

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

I wonder where to run the command above to check RESTful APIs. I know it's Rust Cargo command, and I tried running this command in docker container which holds trailbase but it doesn't work without Rust toolchain installed.

The above command will build and then run trailbase from sources with the optional openapi feature. This means you'll have to run it from within the repo directory with the necessary dependencies installed.

The docker image neither contains the rust toolchain (or any of the other dependencies) nor trailbase built with openapi (significantly inflates the binary size and should never be needed for prod instances).

If you don't want to build a trailbase from source with openapi, is there a specific question I can help you with?

[EMUNES]

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

I wonder where to run the command above to check RESTful APIs. I know it's Rust Cargo command, and I tried running this command in docker container which holds trailbase but it doesn't work without Rust toolchain installed.

The above command will build and then run trailbase from sources with the optional openapi feature. This means you'll have to run it from within the repo directory with the necessary dependencies installed.

The docker image neither contains the rust toolchain (or any of the other dependencies) nor trailbase built with openapi (significantly inflates the binary size and should never be needed for prod instances).

If you don't want to build a trailbase from source with openapi, is there a specific question I can help you with?

Thanks for this clearification. Building from source is one way to extend trailbase. I do have a question about extending Trailbase without touching source. How can we authenticate users from another service?

I know Trailbase have a public key for download. The doc also mentions auth is made of ed25519, JWT and refresh tokens. Combining all above, which specific methods should we use to deal with the public key and authenticate? I think a code example could be good, as the procedure is fixed by Trailbase for other services (a humble suggestion, not rush).

One more thing I noticed when playing with Trailbase: From the admin UI, there seems no way to make the primary key an integer. Does this mean to in Trailbase we should always leverage UUIDv7 over Integer as the primary key? It seems we could create a table with integer as the primary key using sql command (haven't tried yet).

[ignatz]

Thanks for this clearification. Building from source is one way to extend trailbase.

Just to clarify, that was specific for using the openapi feature to explore the REST APIs. This should be orthogonal to extending TB.

How can we authenticate users from another service? I know Trailbase have a public key for download. The doc also mentions auth is made of ed25519, JWT and refresh tokens. Combining all above, which specific methods should we use to deal with the public key and authenticate? I think a code example could be good, as the procedure is fixed by Trailbase for other services (a humble suggestion, not rush).

IIUC, authenticate in this context means another service/binary authenticating a TB user. If so, you're on the right track. Having a code example sounds reasonable, just keep in mind that it will greatly depend on whatever you use in your external service/binary. For all I know you may be running COBOL :). In principle, using your JWT library of choice you should be able to validate the auth token using the public key.

One more thing I noticed when playing with Trailbase: From the admin UI, there seems no way to make the primary key an integer. Does this mean to in Trailbase we should always leverage UUIDv7 over Integer as the primary key? It seems we could create a table with integer as the primary key using sql command (haven't tried yet).

That's an artifact, let me fix that. For context, in the beginning I had it such that APIs could only be declared on strict tables with uuidv7 ids. The latter requirement has been loosened to also support INTEGER pks, so I should update the UI to also reflect that. You can absolutely use the SQL editor to create a table with an INTEGER pk. Eventually trailbase should also support the implicit rowid pk. For now, you'll need an explicit INTEGER pk (which sqlite internally treats as an alias for the rowid).

[ignatz]

I did file #28 to track loosening the PK constraints in the Admin UI.

[EMUNES]

Thanks. That's good to know.

[Kiniber]

Regarding the swagger ui. I will try to build with the command cargo run --features="openapi" -- open-api
Where would I find this swagger ui? whats the endpoint? is it just /api or /swagger?
Sadly it is quite difficult to build this manually for me. I'm always getting an error:
protoc failed: google/protobuf/descriptor.proto: File not found.\nconfig.proto:3:1: Import \"google/protobuf/descriptor.proto\" was not found or had errors.\nconfig.proto:7:8: \"google.protobuf.FieldOptions\" is not defined

Is there a reason to not include the api in the docker version? It would be really nice to just see it in the admin panel.
Also the swagger ui is not mentioned anywhere and I searched for hours for information about the api until I found this issue which mentions it.

Btw tailscale is incredible! I'm currently trying to use it for a tiny hobby project, where I would also need the api details for authentication.

[ignatz]

Hi @Kiniber ,

Sorry for your inconvenience. I take this as to two issues: openapi and building.

For the former, there's a few reasons:

• it's quite heavy both in terms of build times and binary size.
• we'd probably still not want to enable it by default even if it was built in, at least not publicly.
• the general interaction is quite manual and wo regular audits my confidence in correctness is limited.

None of these are show stoppers and I'm certainly not opposed. It hasn't climbed to being my highest priority yet.

Re building, it looks like your protoc compiler is not finding the default include path. Another user had reported a similar issue. It turned out to be a borked protobuf install on windows. Are you on windows?

[Kiniber]

I'm developing on Fedora. I had to google how to install protobuf. I probably messed something up, I will have another look later. Meanwhile I tried the docker way which was successful: sudo docker build . -t trailbase
Is there an easy way to build the swagger api with docker?
If it is not too difficult it could be nice if the example trailbase, that you have running has the swagger api included, so that people can find it somewhere?
I will find a way to build that swagger api, but I probably need some time. Maybe on the weekend.

[Kiniber]

I got it working. I installed protobuf this way:

according to https://protobuf.dev/installation/
Before I had it installed with the package manager.
I can now open the swagger api on port 4004: http://localhost:4004/docs/
Somehow I expected it to be run as part of trailbase and not as a separate application.
That helps a lot to be able to look up the api. Thanks for your help :)