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.parana
      2020-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":"","isEmailAddressVerified":true,"username":"maria","fullName":"Maria"}'  \
        [0-0] Now you can try:
        [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:

        (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.