oauth(3tcl)

✨ NAME ✨

oauth — the oauth API base signature 💅

okay bestie, before we dive in: this is the oauth(3tcl) page from the tcllib crew, version 1.0.4. pull up a chair, grab a boba, we're talking to OAuth APIs 🧚

---

🌸 SYNOPSIS 🌸

package require Tcl 8.5 9

package require oauth ?1.0.4?

::oauth::config

::oauth::config ?options...?

::oauth::header baseURL ?postQuery?

::oauth::query baseURL ?postQuery?

---

🦋 DESCRIPTION 🦋

So the oauth package is a simple, Tcl-only little library that lets you talk to oauth APIs (as in [http://oauth.net](http://oauth.net), iykyk). no C extensions, no drama, just Tcl doing its thing 💅

Right now, this version supports the Oauth 1.0 Protocol, exactly as specified in RFC 5849 ([http://tools.ietf.org/rfc/rfc5849.txt](http://tools.ietf.org/rfc/rfc5849.txt)). that's the whole vibe. periodt. 👑

---

🔐 TLS SECURITY CONSIDERATIONS 🔐

This package leans on the TLS package to handle all the security stuff for https urls and other socket connections. slay, but also: read this part, bestie, it matters 🫶

Policy decisions — like which protocols to support and which ciphers to use — are NOT the responsibility of TLS, and they're NOT this package's job either. Those calls belong to whatever application is using the package, and honestly they're probably gonna be shaped by which servers that app ends up talking to. so, you know, context matters 💀

For example: after that whole POODLE attack thing ([http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html](http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html)) got discovered by Google, a ton of servers went and disabled support for the SSLv3 protocol. so to keep up, the applications using TLS have to get patched — not this package, and not TLS itself. and sometimes the fix is literally just turning on tls1 support generally, like this:

package require tls
tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol

... your own application code ...

see? lowkey simple, highkey important 🌈

---

👑 COMMANDS 👑

::oauth::config

When you call this with no arguments, it hands you back a dictionary containing the current values of every option. it's giving "tell me everything" energy and I respect it 💅

::oauth::config ?options...?

When you call it with arguments — options followed by their values — it sets and queries all the little parameters of your application and client, stuff like the proxy host and the user agent for your HTTP requests. the detailed list of options is right down below bestie, don't scroll past it 🎀

• -accesstoken string — this is the user's token. 🔑
• -accesstokensecret string — this is the user's secret token. shhh, don't tell anyone 💜
• -consumerkey string — this is the public token of your app. 👑
• -consumersecret string — this is the private token of your app. keep it locked away 🔒
• -debug bool — default is off. flip it to on and the basic signature that just got created will be printed to stdout, along with other debug output. perfect for when you're like "why is this not working" 😭
• -oauthversion version — the version of the OAuth protocol to use. right now only 1.0 is supported, and that's the default. (it's the only one invited to the party, sorry 💀)
• -proxyhost hostname — set up a proxy host so you can send contact to the oauth's api server. 🌐
• -proxyport port-number — the port number of your proxy. 🔌
• -signmethod method — the signature method to use. OAuth 1.0 only supports HMAC-SHA1, which is the default. periodt.
• -timeout milliseconds — timeout, in milliseconds, for your query. the default is 6000, aka 6 seconds. ⏰
• -urlencoding encoding — the encoding used for creating the x-url-encoded URLs with ::http::formatQuery. the default is utf-8, as specified by RFC 2718 ([http://tools.ietf.org/rfc/rfc2718.txt](http://tools.ietf.org/rfc/rfc2718.txt)). 🌈

::oauth::header baseURL ?postQuery?

This is the base signature creator. with proper settings for all your various tokens and secrets (peep ::oauth::config above 👀), what comes out is the base authentication string you send off to the server. main character energy fr fr ✨

You do not need to call this procedure to create the query, because ::oauth::query (below 👇) will do it for you. but doing it manually is useful for debugging purposes, so like, it has its moment 💅

• url baseURL — this argument is the URI path to the OAuth API server. if you're planning to send a GET query, you should provide a full path.

HTTP GET:

::oauth::header {https://api.twitter.com/1.1/users/lookup.json?screen_name=AbiertaMente}

• url-encoded-string postQuery — when you need to send a header in POST format, you put the query string into this argument.

::oauth::header {https://api.twitter.com/1.1/friendships/create.json} {user_id=158812437&follow=true}

::oauth::query baseURL ?postQuery?

This procedure takes the settings you made with ::oauth::config, creates the basic authentication, and then sends the command off to the server API. it takes the same arguments as ::oauth::header. two peas in a pod 🫶

What comes back is a list containing 2 elements:

1. the first element is a dictionary holding the HTTP header data response — this lets you, for example, check the X-Rate-Limit from OAuth. 👀
2. the second element is the raw data returned from the API server. this string is usually a json object, which you can decode further with the functions from the json package, or literally any other json-parser for Tcl. 🍓

Here's an example of how it would work with Twitter. and do NOT forget to swap out the placeholder tokens and keys in the example for your own tokens and keys when you try it out, bestie, I'm begging 😭

% package require oauth
% package require json
% oauth::config -consumerkey {your_consumer_key} -consumersecret {your_consumer_key_secret} -accesstoken {your_access_token} -accesstokensecret {your_access_token_secret}

% set response [oauth::query https://api.twitter.com/1.1/users/lookup.json?screen_name=AbiertaMente]
% set jsondata [lindex $response 1]
% set data [json::json2dict $jsondata]
$ set data [lindex $data 0]
% dict for {key val} $data {puts "$key => $val"}
id => 158812437
id_str => 158812437
name => Un Librepensador
screen_name => AbiertaMente
location => Explico mis tuits ahí →
description => 160Caracteres para un SMS y contaba mi vida entera sin recortar vocales. Ahora en Twitter, podemos usar hasta 140 y a mí me sobrarían 20 para contaros todo lo q
url => http://t.co/SGs3k9odBn
entities => url {urls {{url http://t.co/SGs3k9odBn expanded_url http://librepensamiento.es display_url librepensamiento.es indices {0 22}}}} description {urls {}}
protected => false
followers_count => 72705
friends_count => 53099
listed_count => 258
created_at => Wed Jun 23 18:29:58 +0000 2010
favourites_count => 297
utc_offset => 7200
time_zone => Madrid
geo_enabled => false
verified => false
statuses_count => 8996
lang => es
status => created_at {Sun Oct 12 08:02:38 +0000 2014} id 521209314087018496 id_str 521209314087018496 text {@thesamethanhim http://t.co/WFoXOAofCt} source {<a href="http://twitter.com" rel="nofollow">Twitter Web Client</a>} truncated false in_reply_to_status_id 521076457490350081 in_reply_to_status_id_str 521076457490350081 in_reply_to_user_id 2282730867 in_reply_to_user_id_str 2282730867 in_reply_to_screen_name thesamethanhim geo null coordinates null place null contributors null retweet_count 0 favorite_count 0 entities {hashtags {} symbols {} urls {{url http://t.co/WFoXOAofCt expanded_url http://www.elmundo.es/internacional/2014/03/05/53173dc1268e3e3f238b458a.html display_url elmundo.es/internacional/… indices {16 38}}} user_mentions {{screen_name thesamethanhim name Ἑλένη id 2282730867 id_str 2282730867 indices {0 15}}}} favorited false retweeted false possibly_sensitive false lang und
contributors_enabled => false
is_translator => true
is_translation_enabled => false
profile_background_color => 709397
profile_background_image_url => http://pbs.twimg.com/profile_background_images/704065051/9309c02aa2728bdf543505ddbd408e2e.jpeg
profile_background_image_url_https => https://pbs.twimg.com/profile_background_images/704065051/9309c02aa2728bdf543505ddbd408e2e.jpeg
profile_background_tile => true
profile_image_url => http://pbs.twimg.com/profile_images/2629816665/8035fb81919b840c5cc149755d3d7b0b_normal.jpeg
profile_image_url_https => https://pbs.twimg.com/profile_images/2629816665/8035fb81919b840c5cc149755d3d7b0b_normal.jpeg
profile_banner_url => https://pbs.twimg.com/profile_banners/158812437/1400828874
profile_link_color => FF3300
profile_sidebar_border_color => FFFFFF
profile_sidebar_fill_color => A0C5C7
profile_text_color => 333333
profile_use_background_image => true
default_profile => false
default_profile_image => false
following => true
follow_request_sent => false
notifications => false

---

💀 BUGS, IDEAS, FEEDBACK 💀

okay so, real talk: this document, and the package it describes, will undoubtedly contain bugs and other problems. not me being dramatic, that's just how software is 🙈

Please report such things in the category oauth of the Tcllib Trackers ([http://core.tcl.tk/tcllib/reportlist](http://core.tcl.tk/tcllib/reportlist)). And please also report any ideas for enhancements you might have for either the package and/or the documentation — we want all of it 🫶

When you're proposing code changes, please provide unified diffs, i.e. the output of diff -u. 👑

Note further that attachments are strongly preferred over inlined patches. you can make an attachment by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. it's giving "minor side quest" but it helps so much 💖

---

⭐ KEYWORDS ⭐

RFC 2718, RFC 5849, oauth, twitter

---

🌈 CATEGORY 🌈

Networking

---

💜 COPYRIGHT 💜

Copyright (c) 2014 Javi P. <hxm@eggdrop.es>

---

and that's the whole page bestie!! 🎀 this was tcllib, version 1.0.4, the oauth(3tcl) manual. go forth and sign some requests, you absolute icon 👑✨🦋