diff --git a/CHANGELOG.md b/CHANGELOG.md
index 686b6ac..f5865d2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -23,6 +23,8 @@
 
 ## Non-breaking changes
 
+* Added a `resourceOwnerPasswordGrant` method.
+
 * The `scopes` argument to `AuthorizationCodeGrant.getAuthorizationUrl()` and
   `new Credentials()` and the `newScopes` argument to `Credentials.refresh` now
   take an `Iterable` rather than just a `List`.
diff --git a/README.md b/README.md
index ac6f501..ad3b0c0 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,3 @@
-# overview
 A client library for authenticating with a remote service via OAuth2 on
 behalf of a user, and making authorized HTTP requests with the user's OAuth2
 credentials.
@@ -15,14 +14,14 @@
 authorization. At the time of writing, this library only supports the
 [AuthorizationCodeGrant][] and [resourceOwnerPasswordGrant][] methods, but
 further methods may be added in the future. The following example uses this
-method to authenticate, and assumes that the library is being used by a server-side
-application.
+method to authenticate, and assumes that the library is being used by a
+server-side application.
 
 [AuthorizationCodeGrant]: http://www.dartdocs.org/documentation/oauth2/latest/index.html#oauth2/oauth2.AuthorizationCodeGrant
 [resourceOwnerPasswordGrant]: http://www.dartdocs.org/documentation/oauth2/latest/index.html#oauth2/oauth2.resourceOwnerPasswordGrant
 
-# examples
-## authorization code grant
+## Authorization Code Grant
+
 ```dart
 import 'dart:io'
 import 'package:oauth2/oauth2.dart' as oauth2;
@@ -112,14 +111,41 @@
   print(result);
 }
 ```
-## resource owner password grant
 
-```
-    // Get a fully authorized client
-   var client = await oauth2.resourceOwnerPasswordGrant(
-          authorizationEndpoint, 'username', 'userpass',
-          clientId: 'client', clientSecret: 'secret');
-   // Interact with server using the authorized client
-   var result =  client.read("http://example.com/protected-resources.txt");
+## Resource Owner Password Grant
 
+```dart
+// This URL is an endpoint that's provided by the authorization server. It's
+// usually included in the server's documentation of its OAuth2 API.
+final authorizationEndpoint =
+    Uri.parse("http://example.com/oauth2/authorization");
+
+// The user should supply their own username and password.
+final username = "example user";
+final password = "example password";
+
+// The authorization server may issue each client a separate client
+// identifier and secret, which allows the server to tell which client
+// is accessing it. Some servers may also have an anonymous
+// identifier/secret pair that any client may use.
+//
+// Some servers don't require the client to authenticate itself, in which case
+// these should be omitted.
+final identifier = "my client identifier";
+final secret = "my client secret";
+
+// Make a request to the authorization endpoint that will produce the fully
+// authenticated Client.
+var client = await oauth2.resourceOwnerPasswordGrant(
+    authorizationEndpoint, username, password,
+    identifier: identifier, secret: secret);
+
+// Once you have the client, you can use it just like any other HTTP client.
+var result = await client.read("http://example.com/protected-resources.txt");
+
+// Once we're done with the client, save the credentials file. This will allow
+// us to re-use the credentials and avoid storing the username and password
+// directly.
+new File("~/.myapp/credentials.json")
+    .writeAsString(client.credentials.toJson());
 ```
diff --git a/lib/src/client.dart b/lib/src/client.dart
index adf53d5..c27ab4e 100644
--- a/lib/src/client.dart
+++ b/lib/src/client.dart
@@ -12,7 +12,6 @@
 import 'authorization_exception.dart';
 import 'credentials.dart';
 import 'expiration_exception.dart';
-import 'utils.dart';
 
 // TODO(nweiz): Add an onCredentialsRefreshed event once we have some event
 // infrastructure.
@@ -79,7 +78,8 @@
   /// Creates a new client from a pre-existing set of credentials.
   ///
   /// When authorizing a client for the first time, you should use
-  /// [AuthorizationCodeGrant] instead of constructing a [Client] directly.
+  /// [AuthorizationCodeGrant] or [resourceOwnerPasswordGrant] instead of
+  /// constructing a [Client] directly.
   ///
   /// [httpClient] is the underlying client that this forwards requests to after
   /// adding authorization credentials to them.
diff --git a/lib/src/resource_owner_password_grant.dart b/lib/src/resource_owner_password_grant.dart
index 3d06a6d..28498ca 100644
--- a/lib/src/resource_owner_password_grant.dart
+++ b/lib/src/resource_owner_password_grant.dart
@@ -2,61 +2,69 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
-library resource_owner_password_grant;
+library oauth2.resource_owner_password_grant;
 
 import 'dart:async';
-import 'dart:convert';
+
 import 'package:http/http.dart' as http;
-import 'package:crypto/crypto.dart';
+
 import 'client.dart';
 import 'handle_access_token_response.dart';
 import 'utils.dart';
 
-/// Implementation of the [resource owner password grant] (http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-4.3) for oauth 2.
+/// Obtains credentials using a [resource owner password grant][].
 ///
-
-/// Returns a fully-authorized [Client] if authorization is successful.
+/// This mode of authorization uses the user's username and password to obtain
+/// an authentication token, which can then be stored. This is safer than
+/// storing the username and password directly, but it should be avoided if any
+/// other authorization method is available, since it requires the user to
+/// provide their username and password to a third party (you).
 ///
-/// The client can provide a [clientId] and [clientSecret] for authenticating itself  as required by the server. The
-/// default authentication is basic authentication as recommended by the spec. This can be overridden to be passed as
-/// query parameters by passing [useBasicAuth]: false.
+/// The client [identifier] and [secret] may be issued by the server, and are
+/// used to identify and authenticate your specific OAuth2 client. These are
+/// usually global to the program using this library.
 ///
-/// Specific scopes can be requested vis [scopes], but is not required.  The server may choose to grant less scopes than
-/// actually requested.  The actual scopes granted are returned in [Credentials] property of the [Client].
-///
+/// The specific permissions being requested from the authorization server may
+/// be specified via [scopes]. The scope strings are specific to the
+/// authorization server and may be found in its documentation. Note that you
+/// may not be granted access to every scope you request; you may check the
+/// [Credentials.scopes] field of [Client.credentials] to see which scopes you
+/// were granted.
 Future<Client> resourceOwnerPasswordGrant(
-    Uri authorizationEndpoint, String username, String password,
-    {String clientId,
-    String clientSecret,
-    List<String> scopes: const [],
-    bool useBasicAuth: true,
+    Uri authorizationEndpoint,
+    String username,
+    String password,
+    {String identifier,
+    String secret,
+    Iterable<String> scopes,
+    bool basicAuth: true,
     http.Client httpClient}) async {
-
   var startTime = new DateTime.now();
 
-  var body = {"grant_type": "password", "username": username, "password": password};
+  var body = {
+    "grant_type": "password",
+    "username": username,
+    "password": password
+  };
 
   var headers = {};
 
-  if (clientId != null) {
-    if (useBasicAuth) {
-      headers['authorization'] = 'Basic ' +
-          CryptoUtils.bytesToBase64(UTF8.encode('$clientId:$clientSecret'));
+  if (identifier != null) {
+    if (basicAuth) {
+      headers['Authorization'] = basicAuthHeader(identifier, secret);
     } else {
-      body['client_id'] = clientId;
-      if(clientSecret != null) body['client_secret'] = clientSecret;
+      body['client_id'] = identifier;
+      if (secret != null) body['client_secret'] = secret;
     }
   }
 
-  if (!scopes.isEmpty) body['scope'] = scopes.join(' ');
+  if (scopes != null && !scopes.isEmpty) body['scope'] = scopes.join(' ');
 
-  if (httpClient == null) {
-    httpClient = new http.Client();
-  }
-
-  var response = await httpClient.post(authorizationEndpoint, headers: headers, body: body);
+  if (httpClient == null) httpClient = new http.Client();
+  var response = await httpClient.post(authorizationEndpoint,
+      headers: headers, body: body);
 
   var credentials = await handleAccessTokenResponse(
       response, authorizationEndpoint, startTime, scopes);
-  return new Client(credentials, identifier: clientId, secret: clientSecret);
+  return new Client(credentials, identifier: identifier, secret: secret);
 }
diff --git a/pubspec.yaml b/pubspec.yaml
index f52b8be..bd6bd4c 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -1,5 +1,5 @@
 name: oauth2
-version: 1.0.0-dev
+version: 1.0.0
 author: Dart Team <misc@dartlang.org>
 homepage: http://github.com/dart-lang/oauth2
 description: >
diff --git a/test/resource_owner_password_grant_test.dart b/test/resource_owner_password_grant_test.dart
index dc4631f..1d73a0f 100644
--- a/test/resource_owner_password_grant_test.dart
+++ b/test/resource_owner_password_grant_test.dart
@@ -1,45 +1,48 @@
 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
+
 @TestOn("vm")
-library resource_owner_password_grant_test;
 
-import 'dart:convert';
 import 'dart:async';
-import 'package:http/http.dart' as http;
-import 'package:crypto/crypto.dart';
+import 'dart:convert';
 
-import 'package:test/test.dart';
+import 'package:crypto/crypto.dart';
+import 'package:http/http.dart' as http;
 import 'package:oauth2/oauth2.dart' as oauth2;
+import 'package:test/test.dart';
+
 import 'utils.dart';
 
-final String SUCCESS = JSON.encode({
+final success = JSON.encode({
   "access_token": "2YotnFZFEjr1zCsicMWpAA",
   "token_type": "bearer",
   "expires_in": 3600,
   "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
 });
 
-var auth = 'Basic ${CryptoUtils.bytesToBase64(UTF8.encode('client:secret'))}';
+var auth = 'Basic Y2xpZW50OnNlY3JldA==';
 var authEndpoint = Uri.parse('https://example.com');
-var expectClient = new ExpectClient();
 
 void main() {
+  var expectClient;
+  setUp(() => expectClient = new ExpectClient());
+
   group('basic', () {
     test('builds correct request with client when using basic auth for client',
         () async {
-      expectClient.expectRequest((request) {
+      expectClient.expectRequest((request) async {
         expect(auth, equals(request.headers['authorization']));
         expect(request.bodyFields['grant_type'], equals('password'));
         expect(request.bodyFields['username'], equals('username'));
         expect(request.bodyFields['password'], equals('userpass'));
-        return new Future.value(new http.Response(SUCCESS, 200,
-            headers: {'content-type': 'application/json'}));
+        return new http.Response(success, 200,
+            headers: {'content-type': 'application/json'});
       });
 
       var client = await oauth2.resourceOwnerPasswordGrant(
           authEndpoint, 'username', 'userpass',
-          clientId: 'client', clientSecret: 'secret', httpClient: expectClient);
+          identifier: 'client', secret: 'secret', httpClient: expectClient);
 
       expect(client.credentials, isNotNull);
       expect(client.credentials.accessToken, equals('2YotnFZFEjr1zCsicMWpAA'));
@@ -47,34 +50,34 @@
 
     test('builds correct request when using query parameters for client',
         () async {
-      expectClient.expectRequest((request) {
+      expectClient.expectRequest((request) async {
         expect(request.bodyFields['grant_type'], equals('password'));
         expect(request.bodyFields['client_id'], equals('client'));
         expect(request.bodyFields['client_secret'], equals('secret'));
         expect(request.bodyFields['username'], equals('username'));
         expect(request.bodyFields['password'], equals('userpass'));
-        return new Future.value(new http.Response(SUCCESS, 200,
-            headers: {'content-type': 'application/json'}));
+        return new http.Response(success, 200,
+            headers: {'content-type': 'application/json'});
       });
 
       var client = await oauth2.resourceOwnerPasswordGrant(
           authEndpoint, 'username', 'userpass',
-          clientId: 'client',
-          clientSecret: 'secret',
-          useBasicAuth: false,
+          identifier: 'client',
+          secret: 'secret',
+          basicAuth: false,
           httpClient: expectClient);
       expect(client.credentials, isNotNull);
       expect(client.credentials.accessToken, equals('2YotnFZFEjr1zCsicMWpAA'));
     });
 
     test('builds correct request using scope', () async {
-      expectClient.expectRequest((request) {
+      expectClient.expectRequest((request) async {
         expect(request.bodyFields['grant_type'], equals('password'));
         expect(request.bodyFields['username'], equals('username'));
         expect(request.bodyFields['password'], equals('userpass'));
         expect(request.bodyFields['scope'], equals('one two'));
-        return new Future.value(new http.Response(SUCCESS, 200,
-            headers: {'content-type': 'application/json'}));
+        return new http.Response(success, 200,
+            headers: {'content-type': 'application/json'});
       });
 
       var client = await oauth2.resourceOwnerPasswordGrant(
@@ -87,22 +90,22 @@
     test('merges with existing query parameters', () async {
       var authEndpoint = Uri.parse('https://example.com?query=value');
 
-      expectClient.expectRequest((request) {
+      expectClient.expectRequest((request) async {
         expect(request.bodyFields['grant_type'], equals('password'));
         expect(request.bodyFields['client_id'], equals('client'));
         expect(request.bodyFields['client_secret'], equals('secret'));
         expect(request.bodyFields['username'], equals('username'));
         expect(request.bodyFields['password'], equals('userpass'));
         expect(request.url.queryParameters['query'], equals('value'));
-        return new Future.value(new http.Response(SUCCESS, 200,
-            headers: {'content-type': 'application/json'}));
+        return new http.Response(success, 200,
+            headers: {'content-type': 'application/json'});
       });
 
       var client = await oauth2.resourceOwnerPasswordGrant(
           authEndpoint, 'username', 'userpass',
-          clientId: 'client',
-          clientSecret: 'secret',
-          useBasicAuth: false,
+          identifier: 'client',
+          secret: 'secret',
+          basicAuth: false,
           httpClient: expectClient);
       expect(client.credentials, isNotNull);
       expect(client.credentials.accessToken, equals('2YotnFZFEjr1zCsicMWpAA'));