No internet connection
  1. Home
  2. Documentation
  3. API

Talkyard API authentication

By KajMagnus @KajMagnus2020-04-25 12:01:03.750Z2021-05-22 19:29:26.640Z

To use non-public parts of the API, you need to generate an API secret: Go to https:// your talkyard site /-/admin/settings/features and click Enable API and save the settings. Now, the API tab appears — go there and generate an API secret.

Note that this API secret is very secret — don't send it in emails to anyone, don't share it with anyone.

Then, when doing API requests from your server to Talkyard's API, include an Authorization header:

Authorization: Basic BASE64_TEXT

where BASE64_TEXT is: tyid=2:API_SECRET but base64 encoded. "tyid" means Talkyard ID, and 2 is the Sysbot user id.
So, tyid=2 means that the API request is being done as the Sysbot user (Sysbot is a Talkyard user intended for API requests. There's also a System user with id 1 but it cannot do API requests).

And API_SECRET is the API secret you generated in the API tab.

  • 2 replies
  1. J
    João Ferreira @joao.parana2020-06-03 23:40:53.223Z

    Hi @KajMagnus, can you post an curl request example here ?

    Tanks in advance.

    1. KajMagnus @KajMagnus2020-06-04 10:35:37.458Z2020-06-04 11:20:47.024Z

      Hi João, yes, see below, from an end-to-end test that upserst an external user into Talkyard's databse. (Just a test, not any real secrets.)
      Notice the Authorization: Basic ... line.

      curl  \
          -X POST  \
          -H 'Content-Type: application/json'  \
          -H 'Authorization: Basic dGFsa3lhcmRJZD0yOmQ3angxMzhseHZ0ODlqbzNmeW1lY29hcnk='  \
          -d '{"ssoId":"mariasSsoId","primaryEmailAddress":"e2e-test--maria@example.com","isEmailAddressVerified":true,"username":"maria","fullName":"Maria"}'  \
          http://e2e-test-cid-0-0-now-6669.localhost/-/v0/sso-upsert-user-generate-login-secret
      
      [0-0] Now you can try:
          http://e2e-test-cid-0-0-now-6669.localhost/-/v0/login-with-secret?oneTimeSecret=61f99pz5cx0iecsutnbu596p4&thenGoTo=/
      
      [0-0] ... gets back a one time login secret
      [0-0] Got back login secret: 61f99pz5cx0iecsutnbu596p4
      [0-0] ... redirects Maria to the Talkyard login-with-secret endpoint
      [0-0] Go: http://e2e-test-cid-0-0-now-6669.localhost/-/v0/login-with-secret?oneTimeSecret=61f99pz5cx0iecsutnbu596p4&thenGoTo=/by-michael-category-a
      

      This e2e test: https://github.com/debiki/talkyard/blob/b2528e29447cca2efab4b383f7145fbda408c4d3/tests/e2e/specs/sso-login-member-impl.2browsers.test.ts#L174

      (the e2e tests log the API requests they make, as cURL requests, for debugging / developer friendliness)

      The above request should be the same as: curl --user tyid=2:d7jx138lxvt89jo3fymecoary http://e2e-test-cid-0-0-now-6669.localhost/-/v0/ ... where d7jx138lxvt89jo3fymecoary is the API secret (just a dummy test secret).
      ... Oh it's not, instead, the above request uses a deprecated talkyardId=2:d7jx138lxvt89jo3fymecoary format. Should be: tyid= ... nowadays.

      If you go here: https:// your server /-/admin/api and click Show for an API Secret, you'll see that curl --user ... line.