## Grant Token

> **Docs team note:** This is a whole new chapter in the Java SDK docs.

### Description
Use 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.

> **Docs team note:** Please reference the "Token Management System" above to that particular section in the document.

> 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.

> Currently, `grantToken()` is only available for `Users` and `Spaces`. For other requests, use the `grant()` method.

> 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.

> 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.

> **Docs team note:** Wherever you see "`grant()`" in the above text, please reference it to the **Grant** section of the final document.

### Method(s)
```java
this.pubnub.grantToken().ttl(Integer).users(User...).spaces(Space...).meta(Object).sync()
```
|Parameter | Type | Required | Default | Description|
|---|---|---|---|---|
|`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).|
|`users`   |`User..`.   |Optional   |   | A varargs array of `Users` |
|`spaces`   |`Space...`   |Optional   |   | A varargs array of `Spaces` |
|`meta`   |`Integer`   |Optional   |   | Optional metadata object which must be serialazable to a valid JSON object |

In 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.

#### Examples

```java
// Reference a concrete user and request permission to read and update it.
User.id("user_1").read().write();

// Reference every user prefixed with "emp-" and request a permission for creating such users.
User.pattern("emp-.*").create();

// Reference a concrete space and request all possible permissions
Space.id("space_1").read().write().manage().delete().create();

// Reference every space and request read permissions for all of them
Space.pattern(".*").read();
```

### Basic usage

#### Grant token

```java
pubnub.grantToken()
    .ttl(60)
    .users(User.id("user_1").write().create().delete(),
           User.id("user_2").write().create(),
           User.id("user_3").write().create(),
           User.pattern("emp-.*").read())
    .spaces(Space.pattern("room-.*").read().write().manage())
    .async(new PNCallback < PNGrantTokenResult > () {
        @Override
        public void onResponse(PNGrantTokenResult tokenResult, PNStatus pnStatus) {
            if (!pnStatus.isError()) {
                String accessToken = tokenResult.getToken();
                /*
                * With this token, a pubnub client can do everything
                * what's specified in the chain above.
                *
                * In order to take advantage of these granted permissions,
                * a client must add the corresponding accessToken
                * as the authKey parameter to applicable requests.
                */
            }
        }
    });
```

### Response
The `grantToken()` operation returns a `PNGrantTokenResult` which contains the following fields:

|Method | Type | Description|
|---|---|---|
| `getToken` | `String` |A signed token which can be used to access the requested resources for a specific duration. |