API Documentation → OAuth
- How to get started with OAuth and Gowalla
- How to get an access token
- How to make OAuth requests
- Refreshing an access token
- Authorizing your app, in detail
- Example application
- Connect with Gowalla
- Feedback
We’re happy to share the first iteration of OAuth 2 support in the Gowalla API. This enables third-party developers to build applications that can fetch data on behalf of Gowalla users without the need to first obtain their usernames and passwords. In the future, this will enable third-party developers to build applications that act on behalf of Gowalla users to checkin, create spots, and more.
How to get started with OAuth and Gowalla
- Go to your keys listing and click “Add Application”.
- Note that there is a new field on the form for you to enter your Callback URL. This is the URL that Gowalla will redirect users to after they authorize your application.
- Finish filling out the form and click “Create Key”.
- Your listing of API keys will now show both an API key and a secret key. The latter is used to fetch an access token after your application has been authorized by a Gowalla user.
How to get an access token
In order to make API requests on a user’s behalf, you’ll need to obtain an access token. To do so, you’ll redirect the user to Gowalla to authorize your application. If the user authorizes your application, they are redirected back to your application with a code your application can use to obtain an access token.
In greater detail, the authorization flow goes like this:
- Redirect the user to
https://gowalla.com/api/oauth/new. Pass aredirect_uriparameter in the query string to let Gowalla know where to redirect the user to once they’ve authorized or denied your application. This URL must match the callback URL you’ve registered your application with. You must also pass your application's API key using theclient_idparameter. - After the user authorizes or denies access to your application, Gowalla will redirect them to the callback URL you provided when registering your application. The request will either contain an authorization code or an error indicating the user did not authorize your application.
If the user authorized your application, you can then make a
POSTrequest tohttps://api.gowalla.com/api/oauth/token, passing the following parameters:grant_type- always useauthorization_codeclient_id- the API key for your applicationclient_secret- the secret key for your applicationcode- the authorization code from the redirect to your application from Gowallaredirect_uri- the callback URL for your application
If these parameters all match what Gowalla has for your application, an access token will be issued and returned in the response, along the with the Gowalla username for the authorizer, an expiry timestamp and a refresh token for retrieving a new token once your access token expires. The access token is what you will use to make API requests on behalf of the user.
All requests to /api/oauth/* must be over HTTPS.
How to make OAuth requests
To make Gowalla API requests on the behalf of a user, pass the OAuth token in the query string, as a header, or as a parameter in the request body when making a `POST` request.
For example, to look up a user, if you have an access token “01234567890abcdef”, the request would look like this:
GET /users/therealadam?oauth_token=01234567890abcdefTo pass the OAuth token as a header, use the Authorization header like so:
GET /users/therealadam
Authorization: Token token="01234567890abcdef"Pass the OAuth token as a parameter in a `POST` body like so:
POST /checkins
oauth_token=01234567890abcdef&spot_id=123&...Like the existing Gowalla API, you’ll need to provide an Accept header to specify the response format you want. Note that API requests that use OAuth must use HTTPS.
Refreshing an access token
Access tokens expire after two weeks. At that point, you can request a new access token using the refresh token that was issued along with the access token.
Fetching a new access token is much like fetching the original access token, except a couple of the parameters are different.
grant_type- always userefresh_tokenclient_id- the API key for your applicationclient_secret- the secret key for your applicationrefresh_token- the refresh_token issued at the same time as the access token
The response will include a new access token, its expiry timestamp, and a new refresh token. Note that refresh tokens are useable only once and cannot be reused.
Authorizing your app, in detail
curl is the preferred tool of choice at Gowalla for tinkering with the API. Let’s see how we can work through the OAuth authorization flow using our browser and a little bit of curl.
To start the authorization process, your app redirects to Gowalla to start the authorization process. Go to this URL in your browser, using appropriate values for redirect_uri and client_id:
https://gowalla.com/api/oauth/new?redirect_uri=http://example.com/callback&client_id=abc123
When the user authorizes your application, it will redirect the user back to your site. If you're not running a server yet, you'll be able to copy a URL like the following out of the address bar:
http://example.com/callback?code=48b0547514c7c848d326959899d4a88f
If the user denies authorization to your app, they will be redirected back to the application website URL you designated when you created your application key.
Note the code parameter to your application callback. Your application will use this to POST to the Gowalla token URL and fetch an OAuth token:
curl -d 'grant_type=authorization_code' \
-d 'client_id=abc123' \
-d 'client_secret=123abc' \
-d 'code=48b0547514c7c848d326959899d4a88f' \
-d 'redirect_uri=http://example.com/callback' \
'https://gowalla.com/api/oauth/token'
The token is returned as JSON like so:
{
"scope": "read",
"username": "therealadam",
"expires_in": "Wed, 18 Aug 2010 21:53:56 -0000",
"access_token": "def456",
"refresh_token": "456def"
}
If there is an error in your token request, you’ll see an error response like this:
{
"detail": "Invalid authorization code or client credentials.",
"error": "incorrect_client_credentials"
}
As time goes on, the OAuth tokens you fetch will expire. You can fetch a new one without requiring the user to reauthorize your application like so:
curl -d 'grant_type=refresh_token' \
-d 'client_id=abc123' \
-d 'client_secret=123abc' \
-d 'refresh_token=456def' \
'https://gowalla.com/api/oauth/token'
The new token is returned in a familiar JSON response:
{
"username": "therealadam",
"expires_in": "Wed, 01 Sep 2010 16:42:27 -0000",
"access_token": "fed654",
"refresh_token": "654fed"
}
Example application
The example application our OAuth implementation has been tested against is available for your perusal. If you’re not the specification reading type or want to something to sanity check against, give it a look. In addition, you can tinker with a running instance of it.
Connect with Gowalla
We've prepared buttons for your application to use when you link to Gowalla for authorization. The icons come in light on dark and dark on light variants. There are also icons with no text if that fits better into your design.
Download “Connect with Gowalla” buttons
Feedback
You can send feedback to our developer discussion group at gowalla-dev@googlegroups.com.
If you find a case where the protocol is implemented incorrectly, or you’re curious as to why things aren’t working, please let us know.
If you have problems or idea for improvements, please include as much useful information as you can: test cases via curl, references to the spec, or code are quite helpful in getting on the same page.
Thanks for your patience as we get this off the ground. We hope you find it useful!
Handy links
- The OAuth spec (we've implemented draft 8 of the spec)
- Intridea’s oauth2
Sections
Connect with Gowalla
We've prepared buttons for your application to use when you link to Gowalla for authorization. The icons come in light on dark and dark on light variants. There are also icons with no text if that fits better into your design.