RTN15h: token errors, when the library can renew, result in DISCONNEC…

content/realtime/connection.textile

@@ -77,7 +77,7 @@ bc[objc]. ARTRealtime *ably = [[ARTRealtime alloc] initWithKey:@"{{API_KEY}}"];
 }];
 
 bc[swift]. let realtime = ARTRealtime(key: "{{API_KEY}}")
-realtime.connection.on(.Connected) { change in
+realtime.connection.on(.connected) { change in
     print("Connected, that was easy")
 }
 

content/realtime/push/activate-subscribe.textile

@@ -109,7 +109,7 @@ You should now have a couple of methods: <span lang="swift">"@application(_:didR
 ```[swift]
 // In your UIApplicationDelegate class:
 func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
-    ARTPush.didRegisterForRemoteNotificationsWithDeviceToken(deviceToken, realtime: self.getAblyRealtime())
+    ARTPush.didRegisterForRemoteNotifications(withDeviceToken: deviceToken, realtime: self.getAblyRealtime())
 }
 
 func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {

content/realtime/push/admin.textile

@@ -41,14 +41,30 @@ result.errback do |err|
 end
 ```
 
-p(tip). The push notification service is currently in beta. Before you get started, please take a look at the "push service beta notice":/realtime/push#beta.
-
 The push admin API offers three key features:
 
 * "@publish@":#publish for "direct publishing to devices and groups of identified devices":/realtime/push/publish#direct-publishing
 * "@deviceRegistrations@":#device-registrations for registering, updating, listing and deregistering push devices
 * "@channelSubscriptions@":#channel-subscriptions for subscribing, listing and unsubscribing individual devices or groups of identified devices to push notifications published on channels
 
+h3. Push admin access control and device authentication
+
+Operations using the push admin API, as with all other REST APIs, require specific permissions to be present in the credentials presented by a client. The push admin API has two modes of authorization:
+
+* access using the @push-admin@ permission. A client whose credentials contain the @push-admin@ permission has full access to the push admin API, and can manage registrations and subscriptions for all devices;
+
+* access using the @push-subscribe@ permission. A client with @push-subscribe@ is a push target device, and it can manage its registration and any subscription for itself; it is not able to manage push registrations or channel subscriptions for any other device. The credentials presented, as well as containing the @push-subscribe@ permission, must also authenticate the device itself. 
+
+Every push target device has a @deviceId@ and also has device credentials, which are used as the basis for device authentication. When using the push admin API, a device can authenticate itself in two ways:
+
+* by using an Ably token that contains its @deviceId@;
+
+* by using a normal Ably key or token but additionally including a @deviceToken@ - a credential created at registration time that is used to assert the device identity - in a header in the request.
+
+Management of device credentials is performed by the client library, so unless the push admin API is being accessed directly using HTTP, the client application does not need to worry about managing device credentials.
+
+p(tip). The push notification service is currently in beta. Before you get started, please take a look at the "push service beta notice":/realtime/push#beta.
+
 h1. API reference
 
 inline-toc.
@@ -149,7 +165,7 @@ bq(definition#device-get-device).
   default: get("DeviceDetails":#device-details device, callback("ErrorInfo":/realtime/types#error-info err, "DeviceDetails":#device-details device))
   ruby:    "Deferrable":/realtime/types#deferrable get("DeviceDetails":#device-details device) -> yields "DeviceDetails":#device-details
 
-Obtain the @DeviceDetails@ for a device registered for receiving push registrations matching the @deviceId@ argument, or the @id@ attribute of the provided @DeviceDetails@ object.
+Obtain the @DeviceDetails@ for a device registered for receiving push registrations matching the @deviceId@ argument, or the @id@ attribute of the provided @DeviceDetails@ object. Requires @push-admin@ permission or @push-subscribe@ permission together with device authentication matching the requested @deviceId@.
 
 h4. Parameters
 
@@ -182,7 +198,7 @@ bq(definition).
   default: list(Object params, callback("ErrorInfo":/realtime/types#error-info err, "PaginatedResult":#paginated-result<"DeviceDetails":#device-details device> resultPage))
   ruby:    "Deferrable":/realtime/types#deferrable list(Hash params) -> yields "PaginatedResult":#paginated-result<"DeviceDetails":#device-details>
 
-Retrieve all devices matching the params filter as a paginated list of "@DeviceDetails@":#device-details objects.
+Retrieve all devices matching the params filter as a paginated list of "@DeviceDetails@":#device-details objects. Requires @push-admin@ permission.
 
 h4. Parameters
 
@@ -221,7 +237,7 @@ bq(definition).
   default: save("DeviceDetails":#device-details device, callback("ErrorInfo":/realtime/types#error-info err, "DeviceDetails":#device-details device))
   ruby:    "Deferrable":/realtime/types#deferrable save("DeviceDetails":#device-details device) -> yields "DeviceDetails":#device-details
 
-Register a new @DeviceDetails@ object, or update an existing @DeviceDetails@ object with the Ably service.
+Register a new @DeviceDetails@ object, or update an existing @DeviceDetails@ object with the Ably service. Requires @push-admin@ permission or @push-subscribe@ permission together with device authentication matching the requested @deviceId@.
 
 h4. Parameters
 
@@ -257,7 +273,7 @@ bq(definition#device-remove-device).
   default: remove("DeviceDetails":#device-details device, callback("ErrorInfo":/realtime/types#error-info err))
   ruby:    "Deferrable":/realtime/types#deferrable remove("DeviceDetails":#device-details device) -> yield
 
-Remove a device registered for receiving push registrations that matches the @deviceId@ argument, or the @id@ attribute of the provided @DeviceDetails@ object.
+Remove a device registered for receiving push registrations that matches the @deviceId@ argument, or the @id@ attribute of the provided @DeviceDetails@ object. Requires @push-admin@ permission or @push-subscribe@ permission together with device authentication matching the requested @deviceId@.
 
 h4. Parameters
 
@@ -291,7 +307,7 @@ bq(definition).
   default: removeWhere(Object params, callback("ErrorInfo":/realtime/types#error-info err))
   ruby:    "Deferrable":/realtime/types#deferrable remove_where(Hash params) -> yield
 
-Delete all devices matching the params filter.
+Delete all devices matching the params filter. Requires @push-admin@ permission.
 
 h4. Parameters
 
@@ -335,7 +351,7 @@ bq(definition).
   default: get("PushChannelSubscription":#push-channel-subscription channelSubscription, callback("ErrorInfo":/realtime/types#error-info err, "PushChannelSubscription":#push-channel-subscription channelSubscription))
   ruby:    "Deferrable":/realtime/types#deferrable get("PushChannelSubscription":#push-channel-subscription channel_subscription) -> yields "PushChannelSubscription":#push-channel-subscription
 
-Retrieve the push channel subscription that matches the provided "@PushChannelSubscription@":#push-channel-subscription argument. Each "@PushChannelSubscription@":#push-channel-subscription represents a device or set of devices sharing the same "client identifier":/general/authentication#identified-clients registered to a channel to receive push notifications.
+Retrieve the push channel subscription that matches the provided "@PushChannelSubscription@":#push-channel-subscription argument. Each "@PushChannelSubscription@":#push-channel-subscription represents a device or set of devices sharing the same "client identifier":/general/authentication#identified-clients registered to a channel to receive push notifications. Requires @push-admin@ permission.
 
 h4. Parameters
 
@@ -367,7 +383,7 @@ bq(definition).
   default: list(Object params, callback("ErrorInfo":/realtime/types#error-info err, "PaginatedResult":#paginated-result<"PushChannelSubscription":#push-channel-subscription> resultPage))
   ruby:    "Deferrable":/realtime/types#deferrable list(Hash params) -> yields "PaginatedResult":#paginated-result<"PushChannelSubscription":#push-channel-subscription>
 
-Retrieve all push channel subscriptions that match the provided params filter as a paginated list of "@PushChannelSubscription@":#push-channel-subscription objects. Each "@PushChannelSubscription@":#push-channel-subscription represents a device or set of devices sharing the same "client identifier":/general/authentication#identified-clients registered to a channel to receive push notifications.
+Retrieve all push channel subscriptions that match the provided params filter as a paginated list of "@PushChannelSubscription@":#push-channel-subscription objects. Each "@PushChannelSubscription@":#push-channel-subscription represents a device or set of devices sharing the same "client identifier":/general/authentication#identified-clients registered to a channel to receive push notifications. Requires @push-admin@ permission.
 
 h4. Parameters
 
@@ -408,7 +424,7 @@ bq(definition).
   default: listChannels(Object params, callback("ErrorInfo":/realtime/types#error-info err, "PaginatedResult":#paginated-result<String> resultPage))
   ruby:    "Deferrable":/realtime/types#deferrable list_channels(Hash params) -> yields "PaginatedResult":#paginated-result<String>
 
-Retrieve a list of channels with at least one subscribed device as a paginated list of channel name @String@ objects.
+Retrieve a list of channels with at least one subscribed device as a paginated list of channel name @String@ objects. Requires @push-admin@ permission.
 
 h4. Parameters
 
@@ -445,7 +461,7 @@ bq(definition).
   default: save("PushChannelSubscription":#push-channel-subscription channelSubscription, callback("ErrorInfo":/realtime/types#error-info err, "PushChannelSubscription":#push-channel-subscription channelSubscription))
   ruby:    "Deferrable":/realtime/types#deferrable save("PushChannelSubscription":#push-channel-subscription channel_subscription) -> yields "PushChannelSubscription":#push-channel-subscription
 
-Subscribe a device or group of devices sharing a "client identifier":/general/authentication#identified-clients for push notifications published on a channel.
+Subscribe a device or group of devices sharing a "client identifier":/general/authentication#identified-clients for push notifications published on a channel. Requires @push-admin@ permission or, in the case of a subscription associated with a given @deviceId@, @push-subscribe@ permission together with device authentication matching that @deviceId@.
 
 h4. Parameters
 
@@ -477,7 +493,7 @@ bq(definition).
   default: remove("PushChannelSubscription":#push-channel-subscription channelSubscription, callback("ErrorInfo":/realtime/types#error-info err))
   ruby:    "Deferrable":/realtime/types#deferrable remove("PushChannelSubscription":#push-channel-subscription channel_subscription) -> yield
 
-Subscribe a device or group of devices sharing a "client identifier":/general/authentication#identified-clients for push notifications on a channel.
+Subscribe a device or group of devices sharing a "client identifier":/general/authentication#identified-clients for push notifications on a channel. Requires @push-admin@ permission or, in the case of a subscription associated with a given @deviceId@, @push-subscribe@ permission together with device authentication matching that @deviceId@.
 
 h4. Parameters
 
@@ -510,7 +526,7 @@ bq(definition).
   default: removeWhere(Object params, callback("ErrorInfo":/realtime/types#error-info err))
   ruby:    "Deferrable":/realtime/types#deferrable remove_where(Hash params) -> yield
 
-Delete all push channel subscriptions matching the params filter.
+Delete all push channel subscriptions matching the params filter. Requires @push-admin@ permission.
 
 h4. Parameters
 

content/rest-api/index.textile

@@ -22,7 +22,7 @@ jump_to:
     - reset a device's update token#reset-update-token
     - unregister device#delete-device-registration
     - unregister devices#delete-device-registrations
-    - subscribe to a channel#put-channel-subscription
+    - subscribe to a channel#post-channel-subscription
     - unsubscribe from channels#delete-channel-subscription
     - list channel subscriptions#list-channel-subscriptions
     - list channels#list-channels
@@ -359,7 +359,7 @@ Messages can include an optional @extras@ field, used by extensions to Ably's co
 
 h6(#message-extras-push). Send push notification
 
-You can send a push notification to devices "subscribed to the channel":#put-channel-subscription the message is sent to by setting the @push@ field in the @extras@ object, like this:
+You can send a push notification to devices "subscribed to the channel":#post-channel-subscription the message is sent to by setting the @push@ field in the @extras@ object, like this:
 
 bc[json]. {
   <... message fields ...>
@@ -866,7 +866,7 @@ A successful request returns an empty response.
 
 An unsuccessful request returns an error.
 
-h3(#put-channel-subscription). Subscribe to a channel
+h3(#post-channel-subscription). Subscribe to a channel
 
 Subscribe either a single device or all devices associated with a client ID to receive push notifications from messages sent to a channel.
 
@@ -999,7 +999,7 @@ h3(#push-publish). Publish a push notification to a single device
 
 Convenience endpoint to deliver a push notification payload to a single device or set of devices identified by their "client identifier":/general/authentication#identified-clients.
 
-If you want to send a push notification to multiple devices or use a more flexible publish-subscribe architecture so that you don't need to know about recipient devices's details, we recommend you look at "registering devices for push":#post-device-registration, then "subscribe them to channels":#put-channel-subscription, and then "send messages to the channels with push payloads":#message-extras-push.
+If you want to send a push notification to multiple devices or use a more flexible publish-subscribe architecture so that you don't need to know about recipient devices's details, we recommend you look at "registering devices for push":#post-device-registration, then "subscribe them to channels":#post-channel-subscription, and then "send messages to the channels with push payloads":#message-extras-push.
 
 This direct publish endpoint is designed for customers who typically have legacy devices they wish to push directly to, or if they want to publish to all devices for a single user.
 

content/types/_auth_options.textile

@@ -19,9 +19,9 @@ h4.
   ruby:    Attributes
   Python:  Attributes
 
-- <span lang="default">authCallback</span><span lang="csharp">AuthCallback</span><span lang="python">auth_callback</span><span lang="ruby">:auth_callback</span> := A <span lang="default">function</span><span lang="javascript,nodejs">function with the form @function(tokenParams, callback(err, tokenOrTokenRequest))@</span><span lang="java">@TokenCallback@ instance</span><span lang="python">callable (eg a lambda)</span><span lang="ruby">proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter)</span> which is called when a new token is required. The role of the callback is to either generate a signed "@TokenRequest@":/realtime/types#token-request which may then be submitted automatically by the library to the "Ably REST API @requestToken@":/rest-api#request-token; or to provide a valid token in as a "@TokenDetails@":/realtime/types#token-details object. See "an authentication callback example":<%= JsBins.url_for('authentication/auth-callback') %> or "our authentication documentation":/rest/authentication for details of the token request format and associated API calls.<br>__Type: <span lang="default">@Callable@</span><span lang="java">@TokenCallback@</span><span lang="ruby">@Proc@</span><span lang="csharp">@Func<TokenParams, Task<TokenDetails>>@</span>__
+- <span lang="default">authCallback</span><span lang="csharp">AuthCallback</span><span lang="python">auth_callback</span><span lang="ruby">:auth_callback</span> := A <span lang="default">function</span><span lang="javascript,nodejs">function with the form @function(tokenParams, callback(err, tokenOrTokenRequest))@</span><span lang="java">@TokenCallback@ instance</span><span lang="python">callable (eg a lambda)</span><span lang="ruby">proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter)</span> which is called when a new token is required. The role of the callback is to either generate a signed "@TokenRequest@":/realtime/types#token-request which may then be submitted automatically by the library to the "Ably REST API @requestToken@":/rest-api#request-token; or to provide a valid token in as a "@TokenDetails@":/realtime/types#token-details object. See "an authentication callback example":<%= JsBins.url_for('authentication/auth-callback') %> or "our authentication documentation":/rest/authentication for details of the token request format and associated API calls. Please note that the JSON stringified version of @TokenDetails@ or @TokenRequest@ must be less than 128kb.<br>__Type: <span lang="default">@Callable@</span><span lang="java">@TokenCallback@</span><span lang="ruby">@Proc@</span><span lang="csharp">@Func<TokenParams, Task<TokenDetails>>@</span>__
 
-- <span lang="default">authUrl</span><span lang="csharp">AuthUrl</span><span lang="ruby">:auth_url</span><span lang="python">auth_url</span> := A URL that the library may use to obtain a token string (in plain text format), or a signed "@TokenRequest@":/realtime/types#token-request or "@TokenDetails@":/realtime/types#token-details (in JSON format). For example, this can be used by a client to obtain signed token requests from an application server.<br>__Type: <span lang="default">@String@</span><span lang="csharp">@Uri@</span><span lang="swift,objc">@NSURL@</span>__
+- <span lang="default">authUrl</span><span lang="csharp">AuthUrl</span><span lang="ruby">:auth_url</span><span lang="python">auth_url</span> := A URL that the library may use to obtain a token string (in plain text format), or a signed "@TokenRequest@":/realtime/types#token-request or "@TokenDetails@":/realtime/types#token-details (in JSON format). For example, this can be used by a client to obtain signed token requests from an application server. Please note that the JSON stringified version of @TokenDetails@ or @TokenRequest@ must be less than 128kb.<br>__Type: <span lang="default">@String@</span><span lang="csharp">@Uri@</span><span lang="swift,objc">@NSURL@</span>__
 
 - <span lang="default">authMethod</span><span lang="csharp">AuthMethod</span><span lang="ruby">:auth_method</span><span lang="python">auth_method</span> := _<span lang="default">@GET@</span><span lang="ruby">@:get@</span>_ The HTTP verb to use for the request, either <span lang="default">@GET@</span><span lang="ruby">@:get@</span> or <span lang="default">@POST@</span><span lang="ruby">@:post@</span><br>__Type: <span lang="default">@String@</span><span lang="ruby">@Symbol@</span><span lang="csharp">@HttpMethod@</span>__