# Update a grant

> **PATCH** `https://api.us.nylas.com/v3/grants/{grantId}`

Source: https://developer.nylas.com/docs/reference/api/manage-grants/patch_grant_by_id/

Updates the specified grant's stored settings or scope metadata.

**Common use cases:**

- **Rotate a refresh token** — If you obtain a new `refresh_token` from a provider (for example, after a user re-consents in your own OAuth flow), you can update the grant's stored token without deleting and recreating the grant. Pass the new token in `settings.refresh_token`.
- **Update stored scope list** — Update the `scope` array to reflect the scopes the grant currently holds. Note: this only updates the scope metadata stored by Nylas. It does **not** change the actual permissions the provider has granted. To change provider permissions, the user must re-authenticate through the provider's OAuth consent flow.

When you make a `PATCH` request, Nylas replaces all data in the nested object with the information
included in your request. For more information, see
[Updating objects](/docs/reference/api/#updating-objects).

**Authentication:** NYLAS_API_KEY

## Parameters

### Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `grantId` | string | Yes |  |

## Request body

Content-Type: application/json

- `settings` (object) - Provider-specific settings for the grant. For OAuth providers, this typically contains the `refresh_token`. Nylas replaces the entire `settings` object with the value you provide.
- `scope` (array) - Updates the list of OAuth scopes stored on the grant. This updates only Nylas' record of the scopes — it does not change the actual permissions at the provider. To change provider permissions, the user must re-authenticate through the provider's OAuth consent flow.

## Responses

### 200 - Returns Grant object

- `request_id` (string) - ID of the request
- `data` (object)
  - `account_id` (string) - The v2 Nylas account ID. This field appears only if the grant was created by migrating a v2
connected account.
  - `blocked` (boolean) - When `true`, indicates that the grant is blocked from accessing the Nylas APIs.
  - `created_at` (integer) **(required)** - When the grant was created, in seconds using the Unix timestamp format.
  - `email` (string) - The email address associated with the grant. If the provider supports `id_token` and exposes the
user's email address, Nylas automatically extracts this value.
  - `grant_status` (string) - Specifies whether the grant is valid or the user needs to re-authenticate.
  - `id` (string) **(required)** - A unique identifier for the grant.
  - `ip` (string) - The user's client IP address. Mostly useful for
[Hosted OAuth](/docs/v3/auth/hosted-oauth-apikey/).
  - `name` (string) - The user's display name.
  - `provider` (string) **(required)** - The provider that the user authenticated with.
  - `provider_user_id` (string) - The user's provider ID. This field might be changed at any time by the provider.
  - `scope` (array) **(required)** - An array of [granular scopes](/docs/dev-guide/scopes/) associated with the grant. If none are
specified, Nylas uses the default scopes from the
[connector](/docs/reference/api/connectors-integrations/).
  - `settings` (object) - A list of settings associated with the grant. The contents of this object might differ between
grants or depending on the provider.
  - `email_aliases` (array) - An array of found email aliases for this grant. Only returned if special query parameter `expose_aliases` for 
[Get Grant](/docs/reference/api/manage-grants/get_grant_by_id/) is used and set to `true`.
Applicable only for Google and Microsoft grants.
  - `state` (string) - The initial state that was set as part of the authentication process. Nylas passes this value
back to your project without modifying it. You can use this field for verification, or to track
information about the user.
  - `updated_at` (integer) - When the user last authenticated their grant, in seconds using the Unix timestamp format.
Initially, this value is the same as `created_at`.
  - `user_agent` (string) - The user's [client or browser information](https://www.useragents.me/). Mostly useful for
[Hosted OAuth](/docs/v3/auth/hosted-oauth-apikey/).
  - `workspace_id` (string) - The ID of the Workspace the grant belongs to, if any. For grants from providers other than
Agent Accounts, Nylas may omit this field when the grant is in the application's default
workspace.
  - `credential_id` (string) - The ID of the Credential the grant is associated with. Grant will use this Credential for provider communication.

### 400 - Bad Request

- `request_id` (string) **(required)** - ID of the request
- `error` (object) **(required)** - Error object
  - `type` (string) - Type of error
  - `message` (string) - Informative error message
  - `provider_error` (object) - (OPTIONAL) informative error message from provider's side

### 401 - Not Authenticated

- `request_id` (string) **(required)** - ID of the request
- `error` (object) **(required)** - Error object
  - `type` (string) - Type of error
  - `message` (string) - Informative error message
  - `provider_error` (object) - (OPTIONAL) informative error message from provider's side

### 404 - Not Found

- `request_id` (string) **(required)** - ID of the request
- `error` (object) **(required)** - Error object
  - `type` (string) - Type of error
  - `message` (string) - Informative error message
  - `provider_error` (object) - (OPTIONAL) informative error message from provider's side

## Code samples

### cURL

```bash
curl --request PATCH \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --data '{
    "settings": {
      "refresh_token": "<NEW_REFRESH_TOKEN>"
    },
    "scope": ["Mail.Read", "Mail.Send", "User.Read", "offline_access"]
  }'

```

### Node.js SDK

```javascript
import Nylas from "nylas";

const NylasConfig = {
  apiKey: "<NYLAS_API_KEY>",
  apiUri: "<NYLAS_API_URI>",
};

const nylas = new Nylas(NylasConfig);

async function updateGrant() {
  try {
    const grant = await nylas.grants.update({
      grantId: "<NYLAS_GRANT_ID>",
      requestBody: {
        scope: ["mail.ready"],
      },
    });

    console.log("Updated Grant:", grant);
  } catch (error) {
    console.error("Error to update grant:", error);
  }
}

updateGrant();

```

### Python SDK

```python
import sys
from nylas import Client

nylas = Client(
    "<NYLAS_API_KEY>",
    "<NYLAS_API_URI>"
)

grant_id = "<NYLAS_GRANT_ID>"

grant = nylas.grants.update(
  grant_id,
  request_body={
    "scope": ["mail.ready"]
  }
)

print(grant)
```

### Ruby SDK

```ruby
# frozen_string_literal: true

# Load gems
require 'nylas'

# Initialize Nylas client
nylas = Nylas::Client.new(
  api_key: "<NYLAS_API_KEY>"
)

request_body = {
  scope: ["mail.read"]
}

status, _ = nylas.grants.update(grant_id: "a57cdf3e-6580-4097-9d71-a95e867fb79c", request_body: request_body)

puts status
```

### Java SDK

```java
import com.nylas.NylasClient;
import com.nylas.models.*;
import java.util.ArrayList;
import java.util.List;

public class update_grants {
  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
    NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();

    List<String> scope = new ArrayList<>();
    scope.add("mail.read");

    UpdateGrantRequest requestBody = new UpdateGrantRequest.Builder().scopes(scope).build();
    Response<Grant> grant = nylas.grants().update("<NYLAS_GRANT_ID>", requestBody);

    System.out.println(grant);
  }
}
```

### Kotlin SDK

```kotlin
import com.nylas.NylasClient
import com.nylas.models.UpdateGrantRequest

fun main(args: Array<String>) {
  val nylas: NylasClient = NylasClient(
      apiKey = "<NYLAS_API_KEY>"
  )

  val scope = listOf("mail.read")
  val requestBody = UpdateGrantRequest(null, scope)
  val grant = nylas.grants().update("<NYLAS_GRANT_ID>", requestBody);
  
  print(grant)
}
```