OAuth 1.0

Here’s how to authenticate with the API using OAuth 1.0.

URLs and Signature Methods

If you’ve used OAuth before, here’s what you need to get started.

Consumer Registration URL: https://appfigures.com/developers/keys
Request Token URL: https://api.appfigures.com/v2/oauth/request_token
User Authorization URL: https://api.appfigures.com/v2/oauth/authorize
Access Token URL: https://api.appfigures.com/v2/oauth/access_token
Signature Methods: HMAC-SHA1 or PLAINTEXT

Why Use OAuth

Past versions of the API used HTTP Authentication. Basic and Digest modes are simple and well supported, but they have one big problem: the user has to give their credentials directly to a client.

It’s best not to handle user credentials at all. OAuth lets you authenticate a client without ever seeing the user’s username or password. You don’t have to store user passwords, and the user doesn’t have to trust you with them. The user can also revoke your client’s access remotely, which helps if a device is compromised.

The Flow

This guide has two parts. The first, and harder, part is getting the user’s authorization. You only need to do this once, unless the user revokes access. The second part is using that authorization to request protected resources. For example, to request /products/mine for a user, that user first has to approve your access through the authorization process. After that, you can make requests on their behalf.

Detour #1: Scopes (Permissions)

Give an application only the permissions it needs. Scopes let you do that. An API client can request access to only public data, or read-only access to private data. OAuth 1.0 doesn’t define scopes, so we’ve extended the spec to add them. You set them when you create the client credentials and can limit them further when authorizing. Read more in Scopes.

Detour #2: A Note on Signatures

OAuth has a few ways to sign requests. Our API supports HMAC-SHA1 and PLAINTEXT. HMAC-SHA1 is more complicated than PLAINTEXT, but it resists replayed and forged requests over unsecured channels. Our API only accepts HTTPS, so this guide uses PLAINTEXT. It’s simpler, and HTTPS secures the connection.

Getting a User’s Authorization

Here’s what has to happen to make OAuth work:

Obtain a Request Token
Send the user to us so we can verify their identity and ask them to grant authorization
Exchange the Request Token for an Access Token

When you create an API client on the My API Keys page, you get two tokens: a Client Key and a Client Secret. You use these to get a Request Token and Secret. These are temporary and show that you’re starting authorization. Next, you send the user to Appfigures to approve the Request Token. Then you trade it for an Access Token and Secret that prove the user’s authorization.

To make an authorized request, you need 4 things: the Client Key, Client Secret, Access Token, and Access Secret. You get the first two when you create the app. You trade a Request Token/Secret pair for an Access Token/Secret pair after the user authorizes the app.

Obtain Request Token

First, use your client_key and client_secret to get a set of intermediate tokens (oauth_token, oauth_token_secret). These prove that you know the client key and secret and that you’ve started an OAuth flow.

You can also set a scope here with the X-OAuth-Scope header to restrict your application’s permissions. It’s optional. Without it, your Request Token inherits the scope your application was set up with. You can only use it to restrict permissions. It won’t expand them beyond what you selected when you created the application.

https://api.appfigures.com/v2/oauth/request_token is the resource that provides these intermediate Request Token and Secret called oauth_token and oauth_token_secret respectively. You make a request to it with the following parameters:

oauth_consumer_key » your client_key

oauth_callback » where the user should be directed in the next phase (or the string ‘oob’ if you want the user to enter the token manually)

oauth_signature_method » in this case ‘PLAINTEXT’, could be ‘HMAC-SHA1’

oauth_signature » your client_secret and an ampersand (if your client_secret is “dogbert” oauth_signature would be ‘dogbert&’)

These parameters are required. You can pass them to the request_token resource as GET parameters, as data in a form-urlencoded POST, or in the Authorization header of a POST or GET.

Here are cURL commands for all three. In this example, the client_key is ‘mykey’ and the client_secret is ‘dogbert’.

    # In the Authorization header
    curl -XPOST 'https://api.appfigures.com/v2/oauth/request_token'\
        -H'Authorization: OAuth oauth_signature_method=PLAINTEXT,
                                oauth_consumer_key=mykey,
                                oauth_callback=oob,
                                oauth_signature=dogbert&' \
       -H'X-OAuth-Scope: account:read, private:read'



    # In the querystring -- this must be all on one line for you
    curl -XGET 'https://api.appfigures.com/v2/oauth/request_token?
        oauth_signature_method=PLAINTEXT&
        oauth_consumer_key=mykey&
        oauth_callback=oob&
        oauth_signature=dogbert%26' \
       -H'X-OAuth-Scope: account:read, private:read'

    # In the request body with a POST
    curl -XPOST 'https://api.appfigures.com/v2/oauth/request_token' \
        -d'oauth_signature_method=PLAINTEXT' \
        -d'oauth_consumer_key=mykey' \
        -d'oauth_callback=oob' \
        -d'oauth_signature=dogbert%26' \
        -H'X-OAuth-Scope: account:read, private:read'


    # all three ways return the same result:
    oauth_callback_confirmed=true&oauth_token=myotoken&oauth_token_secret=catbert

The ‘&’ is percent-encoded in the last two methods. All values that are not letters, numbers, ‘-’, ‘.’, ‘_’, or ‘~’ should be encoded.

Send the User to Appfigures to Grant Permission

Now that you have an oauth_token and oauth_token_secret, send the user to Appfigures to approve your request. Direct the user to https://api.appfigures.com/v2/oauth/authorize?oauth_token=myotoken, replacing myotoken with the oauth_token you got above.

If the user is already logged in to their Appfigures account, we’ll send them straight to the authorization page. To make the user log in again, add force_login=true to the query string. They’ll have to enter their credentials to approve the app. This won’t log them out of their Appfigures account.

Receive Authorization

When the user approves your request, we redirect them to the oauth_callback you set in step 1 (Obtain Request Token). If the callback is oob (out-of-band), we won’t redirect the user. Instead, we’ll show them a page with the oauth_verifier they’ll need to give your application. How you collect it is up to you.

We append two query string parameters to the callback: oauth_token and oauth_verifier. So if you set your oauth_callback to http://coolapp.com/oauth_callback and the oauth_verifier is ‘certified’ and the oauth_token is ‘myotoken’, we’ll redirect the user to http://coolapp.com/oauth_callback?oauth_token=myotoken&oauth_verifier=certified

With the oauth_verifier, you can exchange the Request Token and Secret (oauth_token and oauth_token_secret) for an Access Token/Secret pair.

https://api.appfigures.com/v2/oauth/access_token is the resource that provides the final Access Token and Secret called oauth_token and oauth_token_secret respectively. You make a request to it with the following parameters:

oauth_consumer_key » your client_key. In this case: ‘mykey’

oauth_token » your Request Token. In this case: ‘myotoken’

oauth_verifier » your oauth_verifier. In this case ‘certified’

oauth_signature_method » in this case ‘PLAINTEXT’, could be ‘HMAC-SHA1’

oauth_signature » your client_secret and Request Secret separated by an ampersand. In this case ‘dogbert&catbert’

    # cURL using the Authorization header scheme
     curl -XGET 'https://api.appfigures.com/v2/oauth/access_token' \
        -H'Authorization: OAuth oauth_signature_method=PLAINTEXT,
                                oauth_verifier=certified,
                                oauth_consumer_key=mykey,
                                oauth_token=myotoken,
                                oauth_signature=dogbert&catbert'

    # returns
    oauth_token=accesstoken&oauth_token_secret=accesssecret

This resource returns the Access Token and Secret the same way the request_token resource returns the Request Token and Secret. Now you have all 4 things you need to make a request:

consumer_key (mykey – your Client Key)
consumer_secret (dogbert – your Client Secret)
oauth_token (accesstoken – the Access Token you just got from /oauth/access_token)
oauth_token_secret (accesssecret – the Access Secret)

Making a Request

Say you want your app to get a list of the authenticated user’s products. You’ve gone through the process above and have all 4 pieces you need: a Client Key, a Client Secret, an Access Token and an Access Secret.

Send them in the Authorization header of every request, as in the examples above.

oauth_consumer_key » your client_key. In this case: ‘mykey’
oauth_token » your Access Token. In this case: ‘accesstoken’
oauth_signature_method » in this case ‘PLAINTEXT’, could be ‘HMAC-SHA1’
oauth_signature » your client_secret and Access Secret separated by an ampersand. In this case ‘dogbert&accesssecret’

Put them all in an Authorization header like this:

    Authorization:  OAuth oauth_signature_method=PLAINTEXT,
                          oauth_consumer_key=mykey,
                          oauth_token=accesstoken,
                          oauth_signature=dogbert&accesssecret

A request for a user’s products looks like this:

    GET https://api.appfigures.com/v2/products/mine HTTP/1.1
    Authorization: OAuth oauth_signature_method=PLAINTEXT,
                         oauth_consumer_key=mykey,
                         oauth_token=accesstoken,
                         oauth_signature=dogbert&accesssecret

Or with cURL:

     curl -XGET 'https://api.appfigures.com/v2/products/mine' \
        -H'Authorization: OAuth oauth_signature_method=PLAINTEXT,
                                oauth_consumer_key=mykey,
                                oauth_token=accesstoken,
                                oauth_signature=dogbert&accesssecret'