Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 144 lines (101 sloc) 7.528 kb
40c4f64 @qrush Rename to Basecamp
qrush authored
1 Basecamp API Authentication
2 ===========================
a594b23 @qrush bring over guidelines, rename to apis repo
qrush authored
3
4 > Speak, friend, and enter.
5
40c4f64 @qrush Rename to Basecamp
qrush authored
6 All Basecamp' products API requests can be authenticated by passing along an OAuth 2 token. API keys are supported as well for some apps.
a594b23 @qrush bring over guidelines, rename to apis repo
qrush authored
7
8 Basic Auth (new Basecamp only)
9 ------------------------------
10
11 To hit the ground running with the all new Basecamp's API, just use HTTP Basic authentication with your own login info:
12
13 ```shell
14 curl -u username:password -H 'User-Agent: MyApp (yourname@example.com)' https://basecamp.com/999999999/api/v1/projects.json
15 ```
16 _Never ask a user of your application for their username or password!_
17
18 You're free to use your own username & password to access your own account and
19 to get started with the API. OAuth 2 is a simple protocol, but it's yet another
20 speed bump to getting an integration off the ground.
21
22 Your HTTP client software includes built-in support for HTTP Basic authentication.
23 Just provide your username and password.
24
25 API Key
26 -------
27
28 Basecamp Classic, Highrise, Campfire, and Backpack allow usage of an API token to authenticate:
29
30 ```shell
31 curl -u 605b32dd:X https://sample.campfirenow.com/room/1.xml
32 ```
33
34 Remember that anyone who has your authentication token can see and change everything you have access to. So you want to guard that as well as you guard your username and password. If you come to fear that it has been compromised, just change your regular password and the authentication token will change too.
35
36 OAuth 2
37 -------
38
39 For a full app integration, you wouldn't want to get into the business of asking
40 customers for their passwords -- or storing them! -- so we offer a simple way to
41 ask a user for access to his account. You get an API access token back without
42 ever having to see his password or ask him to copy/paste an API key.
43
44 1. [Grab an OAuth 2 library](http://oauth.net/code/).
45 2. Register your app at [integrate.37signals.com](https://integrate.37signals.com). You'll be assigned a `client_id` and `client_secret`. You'll need to provide a `redirect_uri`: a URL where we can send a verification code. Just enter a dummy URL like `http://myapp.com/oauth` if you're not ready for this yet.
46 3. Configure your OAuth 2 library with your `client_id`, `client_secret`, and `redirect_uri`. Tell it to use `https://launchpad.37signals.com/authorization/new` to request authorization and `https://launchpad.37signals.com/authorization/token` to get access tokens.
60649ad @qrush Add docs and clarification for authorization endpoint
qrush authored
47 4. Try making an authorized request to `https://launchpad.37signals.com/authorization.json` to dig in and test it out! Check out the [Get authorization](#get-authorization) endpoint for a description of what this returns.
a594b23 @qrush bring over guidelines, rename to apis repo
qrush authored
48
49
50 OAuth 2 from scratch
51 --------------------
52
53 If you're going bare-metal and developing your own OAuth 2 client, you have a bit more work to do.
54
55 **TL;DR** request access, receive a verification code, trade it for an access token.
56
57 The typical flow for a web app:
58
59 1. Your app requests authorization by redirecting your user to Launchpad:
60
61 https://launchpad.37signals.com/authorization/new?type=web_server&client_id=your-client-id&redirect_uri=your-redirect-uri
62
40c4f64 @qrush Rename to Basecamp
qrush authored
63 2. We authenticate their Basecamp ID and ask whether it's ok to give access to your app. [Here's an example of what this screen looks like](https://launchpad.37signals.com/authorization/new?type=web_server&client_id=0bf18204f5a28003bf7b9abb7e1db5e649d86ef4&redirect_uri=moist%3A%2F%2Foauth)
a594b23 @qrush bring over guidelines, rename to apis repo
qrush authored
64
65 3. We redirect the user back to your app with a time-limited verification code.
66
67 4. Your app makes a backchannel request to trade the verification code for an access token. We authenticate your app and issue an access token:
68
69 POST https://launchpad.37signals.com/authorization/token?type=web_server&client_id=your-client-id&redirect_uri=your-redirect-uri&client_secret=your-client-secret&code=verification-code
70
40c4f64 @qrush Rename to Basecamp
qrush authored
71 5. Your app uses the token to authorize API requests to any of the Basecamp ID's accounts. Set the Authorization request header:
a594b23 @qrush bring over guidelines, rename to apis repo
qrush authored
72
96f95b9 @qrush Clarify Authorization header
qrush authored
73 Authorization: Bearer YOUR_OAUTH_TOKEN
a594b23 @qrush bring over guidelines, rename to apis repo
qrush authored
74
40c4f64 @qrush Rename to Basecamp
qrush authored
75 6. To get info about the Basecamp ID you authorized and the accounts you have access to, make an authorized request to `https://launchpad.37signals.com/authorization.json` (or `/authorization.xml`). (See
a594b23 @qrush bring over guidelines, rename to apis repo
qrush authored
76
77 Implementation notes:
78
79 * Start by reading the [draft spec](http://tools.ietf.org/html/draft-ietf-oauth-v2)
80 * We implement draft 5 and will update our implementation as the final spec converges. Be prepared for changes along the way.
81 * We support the web_server and user_agent flows, not the client_credentials or device flows.
82 * We issue refresh tokens. Use them to request a new access token when it expires (2 week lifetime, currently).
83 * We return more verbose errors than what's given in the spec to help with client development. We'll move these to a separate parameter later.
60649ad @qrush Add docs and clarification for authorization endpoint
qrush authored
84
85
86 Get authorization
87 -----------------
88
89 * `GET https://launchpad.37signals.com/authorization.json`
90 * `GET https://launchpad.37signals.com/authorization.xml`
91
bfc8493 @qrush Clarify who am I, and where to get who I am
qrush authored
92 This endpoint requires the `Authorization` header and returns the following:
60649ad @qrush Add docs and clarification for authorization endpoint
qrush authored
93
94 * A `expires_at` timestamp for when this token will expire, and you'll need to fetch a new one to authenticate requests
95 * An `identity`, which is **NOT** used for determining who this user is within a specific application. The `id` field should **NOT** be used for submitting data within any application's API. This field can be used to get a user's name and email address quickly, and the `id` field could be used for caching on a cross-application basis if needed.
96 * A list of `accounts` that this user has access to.
97
98 This endpoint should be first request made after you've obtained a user's authorization token via OAuth. You can pick which account to use for a given product, and then base where to make requests to from the chosen account's `href` field.
99
100 ```json
101 {
102 "expires_at": "2012-03-22T16:56:48-05:00",
103 "identity": {
104 "id": 9999999,
105 "name": "Jason Fried",
40c4f64 @qrush Rename to Basecamp
qrush authored
106 "email_address": "jason@basecamp.com",
60649ad @qrush Add docs and clarification for authorization endpoint
qrush authored
107 },
108 "accounts": [
109 {
110 "product": "bcx",
111 "id": 88888888,
112 "name": "Wayne Enterprises, Ltd.",
113 "href": "https://basecamp.com/88888888/api/v1",
114 },
115 {
116 "product": "bcx",
117 "id": 77777777,
118 "name": "Veidt, Inc",
119 "href": "https://basecamp.com/77777777/api/v1",
120 },
121 {
122 "product": "campfire",
123 "id": 44444444,
124 "name": "Acme Shipping Co.",
125 "href": "https://acme4444444.campfirenow.com"
126 }
127 ]
128 }
129 ```
bfc8493 @qrush Clarify who am I, and where to get who I am
qrush authored
130
131
132 Who am I?
133 ---------
134
40c4f64 @qrush Rename to Basecamp
qrush authored
135 So you've picked the product, have the `href` to request to, and now what? Depending on what your API integration needs, you may need to know who the current user is within that product. For example, if you were working with the [Basecamp API](https://github.com/Basecamp/bcx-api) this is how you would obtain the `id` field to [submit a todo](https://github.com/Basecamp/bcx-api/blob/master/sections/todos.md#create-todo) assigned to the current user.
bfc8493 @qrush Clarify who am I, and where to get who I am
qrush authored
136
137 Here's links to the endpoints in our products that you'll need to hit:
138
40c4f64 @qrush Rename to Basecamp
qrush authored
139 * [Basecamp: Get person](https://github.com/basecamp/bcx-api/blob/master/sections/people.md#get-person)
140 * [Basecamp Classic: Current person](https://github.com/basecamp/basecamp-classic-api/blob/master/sections/people.md#current-person)
141 * [Highrise: Get myself](https://github.com/basecamp/highrise-api/blob/master/sections/users.md#get-myself)
142 * [Campfire: Get self](https://github.com/basecamp/campfire-api/blob/master/sections/users.md#get-self)
143 * [Backpack: Current user](https://github.com/basecamp/backpack-api/blob/master/sections/users.md#current-user)
Something went wrong with that request. Please try again.