Skip to content

feat(nan-5088): scopes remap — accept legacy and new scopes, expand existing keys #6088

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pfreixes merged 18 commits into from
May 19, 2026
Merged

feat(nan-5088): scopes remap — accept legacy and new scopes, expand existing keys #6088

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
26cb13a
feat(nan-5088): scopes remap — accept legacy and new scopes, expand e…
pfreixes May 8, 2026
7a3b8f9
Apply suggestion from @cubic-dev-ai[bot]
pfreixes May 11, 2026
3715246
test: simplify test setup — auto-generate account ids
pfreixes May 11, 2026
a7b422f
Merge branch 'pfreixes/nan-5088-scopes-remap' of github.com:NangoHQ/n…
pfreixes May 11, 2026
1f7e58f
fix: also expand legacy scopes on soft-deleted keys
pfreixes May 11, 2026
be75781
docs: replace legacy scopes with new ones
pfreixes May 11, 2026
ba5ca5d
Merge remote-tracking branch 'origin/master' into pfreixes/nan-5088-s…
pfreixes May 11, 2026
d1ceff3
fix(webapp): expand legacy scope when unchecking a remapped permission
pfreixes May 11, 2026
d80db9f
fix(test): use unique secrets and non-empty iv/tag in expandLegacyApi…
pfreixes May 11, 2026
160e021
refactor(webapp): remove legacy scope expansion in scope picker
pfreixes May 11, 2026
f835032
feat(webapp): strip legacy scopes from migrated keys on save
pfreixes May 11, 2026
42b25a5
fix(webapp): exclude legacy scopes from the count column
pfreixes May 11, 2026
34d995d
fix(webapp): count legacy scopes out of the no-scopes check
pfreixes May 11, 2026
5179fa8
Merge branch 'master' into pfreixes/nan-5088-scopes-remap
pfreixes May 14, 2026
56a88cd
Merge branch 'master' into pfreixes/nan-5088-scopes-remap
pfreixes May 18, 2026
041b6a6
chore(migrations): bump legacy-scope expansion timestamp to today
pfreixes May 18, 2026
29c5c29
Merge remote-tracking branch 'origin/master' into pfreixes/nan-5088-s…
pfreixes May 19, 2026
c5febcd
Merge branch 'master' into pfreixes/nan-5088-scopes-remap
pfreixes May 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/guides/auth/auth-guide.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ Once you have the connection ID, fetch credentials whenever you need them:

The default API key created on signup has full access and is the simplest option.

If the user creates a scoped API key instead, this guide needs `environment:integrations:write` (step 2) and `environment:connect_sessions:write` (steps 5 and 8). See [API keys](/reference/backend/http-api/api-keys).
If the user creates a scoped API key instead, this guide needs `environment:integrations:create` (step 2) and `environment:connect_sessions:write` (steps 5 and 8). See [API keys](/reference/backend/http-api/api-keys).
Copy link
Copy Markdown
Contributor

@kaposke kaposke May 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should environment:connect_sessions:write become environment:connect_sessions:create in this migration as well?

</Accordion>
</Step>

Expand Down
17 changes: 12 additions & 5 deletions docs/reference/backend/http-api/api-keys.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,9 +138,12 @@ The **Default - Full access** key that comes with each environment already has a
|-------|-------------|
| `environment:integrations:list` | List integrations (no credentials) |
| `environment:integrations:list_credentials` | List integrations with client credentials |
| `environment:integrations:list_functions` | List deployed functions (syncs and actions) |
| `environment:integrations:read` | Read a single integration (no credentials) |
| `environment:integrations:read_credentials` | Read a single integration with client credentials |
| `environment:integrations:write` | Create, update, delete integrations |
| `environment:integrations:create` | Create integrations |
| `environment:integrations:update` | Update integrations |
| `environment:integrations:delete` | Delete integrations |

### Connections

Expand All @@ -150,7 +153,9 @@ The **Default - Full access** key that comes with each environment already has a
| `environment:connections:list_credentials` | List connections with access/refresh tokens |
| `environment:connections:read` | Read a single connection (no credentials) |
| `environment:connections:read_credentials` | Read a single connection with access/refresh tokens |
| `environment:connections:write` | Create, update, delete connections and metadata |
| `environment:connections:create` | Create connections |
| `environment:connections:update` | Update connections and metadata |
| `environment:connections:delete` | Delete connections |

### Connect Sessions

Expand All @@ -164,7 +169,9 @@ The **Default - Full access** key that comes with each environment already has a
|-------|-------------|
| `environment:syncs:read` | Read sync status |
| `environment:syncs:execute` | Trigger, pause, start syncs |
| `environment:syncs:manage` | Update sync frequency, create/delete sync variants |
| `environment:syncs:update` | Update sync connection frequency |
| `environment:syncs:variant:create` | Create sync variants |
| `environment:syncs:variant:delete` | Delete sync variants |

### Deploy

Expand All @@ -191,11 +198,11 @@ The **Default - Full access** key that comes with each environment already has a
|-------|-------------|
| `environment:proxy` | Send proxy requests to external APIs through Nango |

### Config
### Variables

| Scope | Description |
|-------|-------------|
| `environment:config:read` | Read environment variables and functions config |
| `environment:variables:read` | Read environment variables |

### MCP

Expand Down
2 changes: 1 addition & 1 deletion docs/reference/backend/http-api/connection/delete.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,5 +4,5 @@ openapi: 'DELETE /connection/{connectionId}'
---

<Info>
Requires an API key with the `environment:connections:write` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
Requires an API key with the `environment:connections:delete` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
</Info>
2 changes: 1 addition & 1 deletion docs/reference/backend/http-api/connection/post.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ openapi: 'POST /connection'
---

<Info>
Requires an API key with the `environment:connections:write` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
Requires an API key with the `environment:connections:create` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
</Info>

## When to use
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/backend/http-api/connection/set-metadata-legacy.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ openapi: 'POST /connection/{connectionId}/metadata'
---

<Info>
Requires an API key with the `environment:connections:write` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
Requires an API key with the `environment:connections:update` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
</Info>

## Set _connection metadata_
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/backend/http-api/connection/set-metadata.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ openapi: 'POST /connection/metadata'
---

<Info>
Requires an API key with the `environment:connections:write` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
Requires an API key with the `environment:connections:update` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
</Info>

## Set _connection metadata_
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/backend/http-api/connection/update-metadata-legacy.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ openapi: 'PATCH /connection/{connectionId}/metadata'
---

<Info>
Requires an API key with the `environment:connections:write` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
Requires an API key with the `environment:connections:update` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
</Info>

## Update _connection metadata_
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/backend/http-api/connection/update-metadata.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ openapi: 'PATCH /connection/metadata'
---

<Info>
Requires an API key with the `environment:connections:write` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
Requires an API key with the `environment:connections:update` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
</Info>

## Update _connection metadata_
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/backend/http-api/connections/delete.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,5 +4,5 @@ openapi: 'DELETE /connections/{connectionId}'
---

<Info>
Requires an API key with the `environment:connections:write` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
Requires an API key with the `environment:connections:delete` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
</Info>
2 changes: 1 addition & 1 deletion docs/reference/backend/http-api/connections/patch.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,5 +4,5 @@ openapi: 'PATCH /connections/{connectionId}'
---

<Info>
Requires an API key with the `environment:connections:write` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
Requires an API key with the `environment:connections:update` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
</Info>
2 changes: 1 addition & 1 deletion docs/reference/backend/http-api/connections/post.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ openapi: 'POST /connections'
---

<Info>
Requires an API key with the `environment:connections:write` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
Requires an API key with the `environment:connections:create` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
</Info>

## When to use
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/backend/http-api/connections/set-metadata.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ openapi: 'POST /connections/metadata'
---

<Info>
Requires an API key with the `environment:connections:write` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
Requires an API key with the `environment:connections:update` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
</Info>

## Set _connection metadata_
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/backend/http-api/connections/update-metadata.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ openapi: 'PATCH /connections/metadata'
---

<Info>
Requires an API key with the `environment:connections:write` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
Requires an API key with the `environment:connections:update` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
</Info>

## Update _connection metadata_
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/backend/http-api/integration/create.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ openapi: 'POST /integrations'
---

<Info>
Requires an API key with the `environment:integrations:write` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
Requires an API key with the `environment:integrations:create` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
</Info>

<ResponseExample>
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/backend/http-api/integration/delete.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,5 +4,5 @@ openapi: 'DELETE /integrations/{uniqueKey}'
---

<Info>
Requires an API key with the `environment:integrations:write` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
Requires an API key with the `environment:integrations:delete` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
</Info>
2 changes: 1 addition & 1 deletion docs/reference/backend/http-api/integration/update.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,5 +4,5 @@ openapi: 'PATCH /integrations/{uniqueKey}'
---

<Info>
Requires an API key with the `environment:integrations:write` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
Requires an API key with the `environment:integrations:update` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
</Info>
2 changes: 1 addition & 1 deletion docs/reference/backend/http-api/scripts/config.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ openapi: 'GET /scripts/config'
---

<Info>
Requires an API key with the `environment:config:read` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
Requires an API key with the `environment:integrations:list_functions` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
</Info>

The `/scripts/config` endpoint returns the configuration for all integration functions. There are two variants of this endpoint:
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/backend/http-api/sync/create-variant.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ openapi: 'POST /sync/{name}/variant/{variant}'
---

<Info>
Requires an API key with the `environment:syncs:manage` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
Requires an API key with the `environment:syncs:variant:create` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
</Info>

## Creating a sync variant
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/backend/http-api/sync/delete-variant.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,5 +5,5 @@ openapi: 'DELETE /sync/{name}/variant/{variant}'
---

<Info>
Requires an API key with the `environment:syncs:manage` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
Requires an API key with the `environment:syncs:variant:delete` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
</Info>
2 changes: 1 addition & 1 deletion docs/reference/backend/http-api/sync/environment-variables.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,5 +4,5 @@ openapi: 'GET /environment-variables'
---

<Info>
Requires an API key with the `environment:config:read` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
Requires an API key with the `environment:variables:read` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
</Info>
2 changes: 1 addition & 1 deletion docs/reference/backend/http-api/sync/update-connection-frequency.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,5 +4,5 @@ openapi: 'PUT /sync/update-connection-frequency'
---

<Info>
Requires an API key with the `environment:syncs:manage` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
Requires an API key with the `environment:syncs:update` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
</Info>
Loading
Loading