RFxYpN97

1## Grant Token
2
3> **Docs team note:** This is a whole new chapter in the Java SDK docs.
4
5### Description
6Use the `grantToken()` method to generate an access token with embedded access control lists. A PubNub client then sends that very token as a query parameter along with a request which may need an authorization token. In order to take advantage of the Token manager which does this job automatically, refer to the ***Token Management System*** section.
7
8> **Docs team note:** Please reference the "Token Management System" above to that particular section in the document.
9
10> Only server-side instances are able to use the `grantToken()` method. In other words, only PubNub instances with a valid secret key are able to do so.
11
12> Currently, `grantToken()` is only available for `Users` and `Spaces`. For other requests, use the `grant()` method.
13
14> Currently, PubNub supports only one regex pattern for each `User` and `Space`. Calling `grantToken()` again with the same user and space patterns will overwrite the existing pattern.
15
16> You can use this method to grant `read`, `write`, `manage`, `delete` and `create` permissions for `Users` and `Spaces`. To grant permissions on an `auth` key that will be used to subscribe to events on `User` and `Space` channels, use the `grant()` method.
17
18> **Docs team note:** Wherever you see "`grant()`" in the above text, please reference it to the **Grant** section of the final document.
19
20### Method(s)
21```java
22this.pubnub.grantToken().ttl(Integer).users(User...).spaces(Space...).meta(Object).sync()
23```
24|Parameter | Type | Required | Default | Description|
25|---|---|---|---|---|
26|`ttl`   |`Integer`   |Yes   |   | The total duration (in minutes) that the token will remain valid. The minimum allowed is 1 minute. The maximum is 43,200 minutes (equivalent to 30 days).|
27|`users`   |`User..`.   |Optional   |   | A varargs array of `Users` |
28|`spaces`   |`Space...`   |Optional   |   | A varargs array of `Spaces` |
29|`meta`   |`Integer`   |Optional   |   | Optional metadata object which must be serialazable to a valid JSON object |
30
31In the Java SDK, and in terms of the `grantToken()` method, applicable resources are instances of `User` and `Space`. Both have static factory methods for to create instances. Also, both feature ways to reference a concrete `User` or `Space` or a regex pattern which applies to multiple `Users` and `Spaces`. Both employ a fluent API to specify which permissions (rights) they need.
32
33#### Examples
34
35```java
36// Reference a concrete user and request permission to read and update it.
37User.id("user_1").read().write();
38
39// Reference every user prefixed with "emp-" and request a permission for creating such users.
40User.pattern("emp-.*").create();
41
42// Reference a concrete space and request all possible permissions
43Space.id("space_1").read().write().manage().delete().create();
44
45// Reference every space and request read permissions for all of them
46Space.pattern(".*").read();
47```
48
49### Basic usage
50
51#### Grant token
52
53```java
54pubnub.grantToken()
55    .ttl(60)
56    .users(User.id("user_1").write().create().delete(),
57           User.id("user_2").write().create(),
58           User.id("user_3").write().create(),
59           User.pattern("emp-.*").read())
60    .spaces(Space.pattern("room-.*").read().write().manage())
61    .async(new PNCallback < PNGrantTokenResult > () {
62        @Override
63        public void onResponse(PNGrantTokenResult tokenResult, PNStatus pnStatus) {
64            if (!pnStatus.isError()) {
65                String accessToken = tokenResult.getToken();
66                /*
67                * With this token, a pubnub client can do everything
68                * what's specified in the chain above.
69                *
70                * In order to take advantage of these granted permissions,
71                * a client must add the corresponding accessToken
72                * as the authKey parameter to applicable requests.
73                */
74            }
75        }
76    });
77```
78
79### Response
80The `grantToken()` operation returns a `PNGrantTokenResult` which contains the following fields:
81
82|Method | Type | Description|
83|---|---|---|
84| `getToken` | `String` |A signed token which can be used to access the requested resources for a specific duration. |