Yammer API Documentation

Why OAuth is Better

Without OAuth, applications would have to ask for the user's email address and password. These credientials would get stored on various devices. The only way for the user to revoke access, would be to change their password. With OAuth, the user knows the only place they should ever enter their Yammer email address and password is in a browser they trust. No passwords are stored on devices. If the user wants to revoke access to a certain client, they can do it from the yammer.com site without affecting other clients.

The following steps below walk through how to use OAuth with the Yammer api.

Step 1.

After filling out this form you will receive a key and secret. If you misplace these values you can see them again.

Note: your key and secret will only work for your Yammer network.

If you want your application's key and secret to work across ALL Yammer networks, you must request this.

For this example my key is:

AMbmZSOP3wHm1cjfvSsRg

And my secret is:

yLDH5eLS4uUVa3vVbNxvDX9B8aFgnwRSFla3jph9y90

Normally you would not reveal these values to the public. But these values and this test app is just for testing.

Step 2.

Choose a programming language and an OAuth library.

You can use Java, PHP, Objective-C, Ruby, Python, Perl, etc. Any language that can make HTTP connections should work. And if there is no OAuth library available, you can write your own. In this example we write all the oauth logic oursevles, but it's very simple. By using the PLAINTEXT signature method we eliminate a big part of the complexity and show you how to debug your program. You can also use an oauth library to handle all the signature methods with PLAINTEXT or HMAC-SHA1. If you are having problems, try writing your own oauth logic with PLAINTEXT as a starting point to find the problem. There is nothing wrong with using PLAINTEXT for real, since yammer uses the https protocol.

Step 3.

Make your key and secret constants in your code:


CONSUMER_KEY = 'AMbmZSOP3wHm1cjfvSsRg'
CONSUMER_SECRET = 'yLDH5eLS4uUVa3vVbNxvDX9B8aFgnwRSFla3jph9y90'

Different languages will have differnent ways of making constats. The above example is "puesdo-code" as is the rest of the code in these steps.

Step 4.

Make an HTTP POST with a special oauth header to get a request token:


    http.setURL('https://www.yammer.com/oauth/request_token')
    http.setHeaderField('Authorization', oauth_headers(null,null,null))
    http.setMethod(POST)

The method oauth_headers takes a token, a token secret, and a verifier. For the first request we pass in null,null,null since we don't any of these values yet.


  String oauth_headers(String token, String token_secret, String verifier) {
    buff.append("OAuth realm=\"");
    buff.append("\", oauth_consumer_key=\"");
    buff.append(CONSUMER_KEY);
    buff.append("\", ");

    if (token != null) {
      buff.append("oauth_token=\"");
      buff.append(token);
      buff.append("\", ");
    }
    
    buff.append("oauth_signature_method=\"");
    buff.append("PLAINTEXT");
    buff.append("\", oauth_signature=\"");
    buff.append(CONSUMER_SECRET);
    buff.append("%26");
    if (token_secret != null) {
      buff.append(token_secret);
    }
    buff.append("\", oauth_timestamp=\"");
    buff.append(currentTime);
    buff.append("\", oauth_nonce=\"");
    buff.append(currentTime);

    if (verifier != null) {
      buff.append("\", ");
      buff.append("oauth_verifier=\"");
      buff.append(verifier);
    }

    buff.append("\", oauth_version=\"1.0\"");

    return buff.toString();
  }

The data sent over the wire should be very similar to:


POST /oauth/request_token HTTP/1.1
User-Agent: Some Yammer Client
Content-Type: application/x-www-form-urlencoded
Authorization: OAuth realm="", oauth_consumer_key="AMbmZSOP3wHm1cjfvSsRg", oauth_signature_method="PLAINTEXT", oauth_signature="yLDH5eLS4uUVa3vVbNxvDX9B8aFgnwRSFla3jph9y90%26", oauth_timestamp="1229537444", oauth_nonce="1229537444", oauth_version="1.0"
Accept: */*
Accept-Language: en-us
Accept-Encoding: gzip, deflate
Connection: keep-alive

You can use wireshark or fiddler or charlesproxy to see this data. Either by changing https://www.yammer.com/oauth/request_token to http://127.0.0.1/oauth/request_token and running a local webserver. Or by intercepting the requests to yammer.

The data that comes back is just text like so:


oauth_token=Fnxef0Gju2zIDQLnh33UKg&oauth_token_secret=qbwGdSFbnOtwywZISFxmoxgp3XN8lyn2HGV2DREZt7g&oauth_callback_confirmed=true

If you get an error message instead of a value for oauth_token and oauth_token_secret, go back and review the steps above. If you do get values, save them to disk, you'll need them for the next step.

Step 5.

Send the user to a browser with the request token so he or she can authorize the request.


browser.openToURL('https://www.yammer.com/oauth/authorize?oauth_token=Fnxef0Gju2zIDQLnh33UKg')

Notice the oauth_token Fnxef0Gju2zIDQLnh33UKg is the same value we got from step 4.

Step 6.

After they clicked "authorize" in the browser the user gets a four digit code and you should be back in your app. You'll know this is not the first time the user has entered the app because there is a request token on disk. Time to turn this request token into an access token.


    http.setURL('https://www.yammer.com/oauth/access_token)
    http.setHeaderField('Authorization', oauth_headers('Fnxef0Gju2zIDQLnh33UKg','qbwGdSFbnOtwywZISFxmoxgp3XN8lyn2HGV2DREZt7g', '1234'))
    http.setMethod(POST)

This time we pass in values for token, token_secret and verifier to oauth_headers. The 1234 is the four digit code the user got after clicking authorize. The data sent over the wire should be very similar to:


POST /oauth/access_token?callback_token=1234 HTTP/1.1
User-Agent: Some Yammer Client
Content-Type: application/x-www-form-urlencoded
Authorization: OAuth realm="", oauth_consumer_key="AMbmZSOP3wHm1cjfvSsRg", oauth_token="Fnxef0Gju2zIDQLnh33UKg", oauth_signature_method="PLAINTEXT", oauth_signature="yLDH5eLS4uUVa3vVbNxvDX9B8aFgnwRSFla3jph9y90%26qbwGdSFbnOtwywZISFxmoxgp3XN8lyn2HGV2DREZt7g", oauth_timestamp="1229537445", oauth_nonce="1229537445", oauth_verifier="1234", oauth_version="1.0"
Accept: */*
Accept-Language: en-us
Accept-Encoding: gzip, deflate
Connection: keep-alive

The data that comes back is just text like so:


oauth_token=BDzef0Gju2zIDQLnh33UKg&oauth_token_secret=aewBdSXbnPtwywZISFxmoxgp3XN8lyn2HGV2DREZt7g

Delete the request token from disk and save this access token to disk. You'll use this access token from now on for each request.

Step 7.

With valid access token, make some simple GET api requests.


    http.setURL('https://www.yammer.com/api/v1/messages')
    http.setHeaderField('Authorization', oauth_headers('BDzef0Gju2zIDQLnh33UKg','aewBdSXbnPtwywZISFxmoxgp3XN8lyn2HGV2DREZt7g', null))
    http.setMethod(GET)

This will return a list of current messages.

Step 8.

Post a new message:


    http.setURL('https://www.yammer.com/api/v1/messages')
    http.setHeaderField('Authorization', oauth_headers('BDzef0Gju2zIDQLnh33UKg','aewBdSXbnPtwywZISFxmoxgp3XN8lyn2HGV2DREZt7g', null))
    http.addParameter('body', 'test message')
    http.setMethod(POST)

When using PLAINTEXT signature method, the parameters you add to a POST do not affect the signature. This is not true when using HMAC-SHA1. PLAINTEXT is much easier to debug and since yammer uses https, it's safe to use PLAINTEXT.

Hopfully the above steps will work for you in your programming language. For more help, try the Yammer Forum and below is a complete example in ruby.

# example run:
# 
# ruby o_auth_example.rb request_token
#{"oauth_token_secret"=>"gGrldPFoa3kIr6Kz7C4DQe0hUxXFWQ24Qim1c48MC4",
# "oauth_callback_confirmed"=>"true",
#  "oauth_token"=>"W9XroyIS6ZePW7qD8kAh5g"}
#
# open browser to https://www.yammer.com/oauth/authorize?oauth_token=W9XroyIS6ZePW7qD8kAh5g
# get back verifier code 1234
#
# ruby o_auth_example.rb access_token W9XroyIS6ZePW7qD8kAh5g gGrldPFoa3kIr6Kz7C4DQe0hUxXFWQ24Qim1c48MC4 1234
#{"oauth_token_secret"=>"y7QP8oUq9NUpXmBs1q727SSqlX0EBzxmuEavbU7YA",
# "oauth_token"=>"OuSqrNQWQVm1LHHmNfmmg"}
#
# ruby o_auth_example.rb messages OuSqrNQWQVm1LHHmNfmmg y7QP8oUq9NUpXmBs1q727SSqlX0EBzxmuEavbU7YA
# [json]
#
# ruby o_auth_example.rb post OuSqrNQWQVm1LHHmNfmmg y7QP8oUq9NUpXmBs1q727SSqlX0EBzxmuEavbU7YA
# [json]

require 'rubygems'
require 'pp'
require 'net/http'
require 'net/https'

CONSUMER_KEY = 'AMbmZSOP3wHm1cjfvSsRg'
CONSUMER_SECRET = 'yLDH5eLS4uUVa3vVbNxvDX9B8aFgnwRSFla3jph9y90'

class OAuthExample

def headers(token, token_secret, oauth_verifier)
    values = {}
    values[:realm]                  = ''
    values[:oauth_consumer_key]     = CONSUMER_KEY
    values[:oauth_token]            = token if token
    values[:oauth_signature_method] = 'PLAINTEXT'
    values[:oauth_signature]        = "#{CONSUMER_SECRET}%26"
    values[:oauth_signature]        = "#{CONSUMER_SECRET}%26#{token_secret}" if token_secret
    values[:oauth_timestamp]        = Time.now.to_i
    values[:oauth_nonce]            = Time.now.to_i
    values[:oauth_version]          = '1.0a'
    values[:oauth_verifier]         = oauth_verifier if oauth_verifier

buffer = []
    [:realm, :oauth_consumer_key, :oauth_token, :oauth_signature_method, 
     :oauth_signature, :oauth_timestamp, :oauth_nonce, :oauth_version, :oauth_verifier].each do |key|
      buffer << "#{key}=\"#{values[key]}\"" if values[key]
    end

"OAuth #{buffer.join(', ')}"
  end

def https_connection(path, authorization, post_data={})
    http = Net::HTTP.new('www.yammer.com', 443)
    http.use_ssl = true
    if post_data == :get
      request = Net::HTTP::Get.new(path)
    else
      request = Net::HTTP::Post.new(path)
      request.set_form_data(post_data, ';') if post_data.size > 0
    end
    request.add_field 'Authorization', authorization
    request.add_field 'Content-Type', 'application/x-www-form-urlencoded'
    request.add_field 'User-Agent', 'Ruby OAuth Example'

response = http.request(request)
    response.body
  end

def parse(raw_data)
    hash = {}
    raw_data.split('&').each do |key_value|
      key, value = key_value.split('=')
      hash[key] = value
    end
    hash
  end

def run

if ARGV[0] == 'request_token'
      pp parse(https_connection('/oauth/request_token', headers(nil, nil, nil)))
    elsif ARGV[0] == 'access_token'
      pp parse(https_connection('/oauth/access_token', headers(ARGV[1], ARGV[2], ARGV[3])))
    elsif ARGV[0] == 'messages'
      puts https_connection('/api/v1/messages.json', headers(ARGV[1], ARGV[2], nil), :get)
    elsif ARGV[0] == 'post'
      params = {'body' => 'test message'}
      puts https_connection('/api/v1/messages.json', headers(ARGV[1], ARGV[2], nil), params)
    end

end
end

t = OAuthExample.new
t.run

Yammer API OAuth Helper

OAuth Step by Step