# Scoped API Keys — Grant fine-grained access to a workspace's resources.


> *Don't see fine-grained permissions for API keys yet?*
>
> Render is in the process of rolling out scoped API keys, which let you choose what each key can access.
>
> If your workspace has not yet received access, continue creating [classic API keys](/docs/api.md#setup). All keys will remain functional after the rollout completes.

All requests to the [Render API](/docs/api.md) must authenticate using an API key. Scoped API keys limit access to resources within a specific workspace, so you can grant each key only the permissions it needs.

If your workspace belongs to an organization, you can also create [audit log API keys](#audit-log-api-keys) to read audit logs for your org and all of its workspaces.

## Setup

### 1. Create an API key

1. Go to your [Account Settings page](https://dashboard.render.com/u/settings?add-api-key) in the Render Dashboard and click *Create API key*.

   [image: The API Keys page in the Render Dashboard]

2. Give your key a name.
3. Select the workspace your key can access.
4. Grant your key permissions. For details, see [Permissions](#permissions).
   - You can also set permissions for _all workspace resources_ at once from the *•••* menu:

     [image: The open permissions menu for granting a key access to all resources]

     - *Enable read-only:* Grants *Read* access to every applicable resource.
     - *Enable all:* Grants every permission your member role allows for every resource.
     - *Disable all:* Removes all permissions from the key.

5. Click *Generate API key*. An API key is shown in full only once, when it's created:

   [image: The API key created dialog showing the new key with a button to copy it]

> *API keys are secret credentials!*
>
> Don't publicly post your API key, commit it to version control, or otherwise share it with anyone outside your organization. If you believe an API key has been compromised, [revoke it](#revoke-an-api-key).

### 2. Make your first request

To test your key, call a Render API endpoint it has permission to access.

For example, a key with *Read* access to [services](#services) can call the [List services](https://api-docs.render.com/reference/list-services.md) endpoint. Replace `{API_KEY}` with your key and run the following:

```bash
curl --request GET \
     --url 'https://api.render.com/v1/services?limit=20' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer {API_KEY}'
```

If your API key is valid, the request returns a `200` response and an array of services.

## Change an key permissions

To change a key's permissions:

1. Go to your [Account Settings page](https://dashboard.render.com/u/settings) in the Render Dashboard and scroll down to the *API Keys* section.
2. Click the gear icon next to the key you want to update:

   [image: An API key row with the Read-Only permissions gear icon highlighted]

3. Change your key's permissions, then click *Save changes*.

## Revoke an API key

> *Revoking an API key takes effect immediately.*
>
> If you're still using the key, replace it _before_ revoking it.

To revoke an API key:

1. Go to your [Account Settings page](https://dashboard.render.com/u/settings) in the Render Dashboard and scroll down to the *API Keys* section.
2. Click the trashcan icon next to the key you want to revoke:

   [image: An API key row with the trashcan icon highlighted]

3. Follow the on-screen instructions to confirm.

## Permissions

Your [*member role*](/docs/team-members.md#member-roles) in the selected workspace determines which permissions you can grant an API key.

The following tables list the permissions you can grant a key for each resource type.

### Services

| Permission | Action | Read | Write | Read &amp; write |
| --- | --- | --- | --- | --- |
| Web and private services, static sites, background workers, and cron jobs | View services and their configuration | 🟢 | ➖ | 🟢 |
| Create, update, and delete services | ❌ | ➖ | 🟢 |  |
| Manage preview environments and one-off jobs | ❌ | ➖ | 🟢 |  |
| Environment variables and secret files | View environment variables and secret files | 🟢 | ❌ | 🟢 |
| Set environment variable and secret file values | ❌ | 🟢 | 🟢 |  |

### Workflows

| Permission | Action | Read | Write | Read &amp; write | Run |
| --- | --- | --- | --- | --- | --- |
| Workflows | View workflows, versions, and task-run inputs and results | 🟢 | ➖ | 🟢 | ➖ |
| Create, update, and delete workflows, and create versions | ❌ | ➖ | 🟢 | ➖ |  |
| Workflow secrets | View workflow environment variables and secret files | 🟢 | ❌ | 🟢 | ➖ |
| Set workflow environment variable and secret file values | ❌ | 🟢 | 🟢 | ➖ |  |
| Run workflow tasks | Trigger and cancel task runs and flow runs | ➖ | ➖ | ➖ | 🟢 |

### Sandboxes

> *Render Sandboxes is in public beta.*
>
> APIs, defaults, and limits might change during the beta period.

| Permission | Action | Read | Write | Read &amp; write | Execute |
| --- | --- | --- | --- | --- | --- |
| Sandbox lifecycle and snapshots | View sandboxes, sandbox groups, and snapshots | 🟢 | ➖ | 🟢 | ➖ |
| View execution history and credential settings | 🟢 | ➖ | 🟢 | ➖ |  |
| Create and terminate sandboxes | ❌ | ➖ | 🟢 | ➖ |  |
| Create, update, and delete sandbox groups | ❌ | ➖ | 🟢 | ➖ |  |
| Create and delete snapshots | ❌ | ➖ | 🟢 | ➖ |  |
| Sandbox execution and file transfer | Run commands in sandboxes | ➖ | ➖ | ➖ | 🟢 |
| Upload and download files | ➖ | ➖ | ➖ | 🟢 |  |
| Manage sandbox credentials | Create, update, and delete credentials | ➖ | 🟢 | ➖ | ➖ |

### Deploys

| Permission | Action | Read | Run |
| --- | --- | --- | --- |
| Deployment information | View deploys, their status, and history | 🟢 | 🟢 |
| Run deployments | Trigger and cancel deploys | ❌ | 🟢 |
| Trigger [rollbacks](/docs/rollbacks.md) | ❌ | 🟢 |  |

### Monitoring

| Permission | Action | Read |
| --- | --- | --- |
| Read resource logs, metrics, events, and export settings | View service events | 🟢 |
| View [service metrics](/docs/service-metrics.md) | 🟢 |  |
| View [service logs](/docs/logging.md) | 🟢 |  |
| View log forwarding and metrics stream settings | 🟢 |  |

### Postgres

| Permission | Action | Read | Write | Read &amp; write |
| --- | --- | --- | --- | --- |
| Postgres instances | View databases and their configuration | 🟢 | ➖ | 🟢 |
| Create, update, and delete databases | ❌ | ➖ | 🟢 |  |
| Postgres credentials and connection details | View connection strings and credentials | 🟢 | ❌ | 🟢 |
| Create and delete database credentials | ❌ | 🟢 | 🟢 |  |
| Postgres exports and backups | View and download exports and backups | 🟢 | ➖ | 🟢 |
| Create exports and backups | ❌ | ➖ | 🟢 |  |

### Key Value

| Permission | Action | Read | Read &amp; write |
| --- | --- | --- | --- |
| Key Value instances | View instances and their configuration | 🟢 | 🟢 |
| Create, update, and delete instances | ❌ | 🟢 |  |
| Read Key Value connection details | View connection URLs and credentials | 🟢 | ➖ |

### Object storage

> *Object storage is in early access.*
>
> During this period, object storage is continuing to evolve and might introduce breaking changes.

| Permission | Action | Read | Read &amp; write |
| --- | --- | --- | --- |
| Objects and blobs | View and download objects | 🟢 | 🟢 |
| Upload and delete objects | ❌ | 🟢 |  |

### Build sources

> *Build reuse is in limited early access.*
>
> During this period, build reuse is continuing to evolve and might introduce breaking changes.

| Permission | Action | Read | Write | Read &amp; write |
| --- | --- | --- | --- | --- |
| Build sources and builds | View build sources, their configuration, and their builds | 🟢 | ➖ | 🟢 |
| Create, update, and delete build sources | ❌ | ➖ | 🟢 |  |
| Trigger builds | ❌ | ➖ | 🟢 |  |
| Build-source environment variables and secret files | View build-source environment variables and secret files | 🟢 | ❌ | 🟢 |
| Set build-source environment variable and secret file values | ❌ | 🟢 | 🟢 |  |

### Workspaces

| Permission | Action | Read | Read &amp; write |
| --- | --- | --- | --- |
| Members, notifications, webhooks, and log and metric streams | View workspace members | 🟢 | 🟢 |
| View [notification settings](/docs/notifications.md) | 🟢 | 🟢 |  |
| View [webhooks](/docs/webhooks.md) | 🟢 | 🟢 |  |
| View log and metric stream settings | 🟢 | 🟢 |  |
| Update member roles and remove members | ❌ | 🟢 |  |
| Update [notification settings](/docs/notifications.md) | ❌ | 🟢 |  |
| Create, update, and delete [webhooks](/docs/webhooks.md) | ❌ | 🟢 |  |
| Update log and metric stream settings | ❌ | 🟢 |  |

### Projects

| Permission | Action | Read | Read &amp; write |
| --- | --- | --- | --- |
| Projects and environments | View projects and environments | 🟢 | 🟢 |
| Create, update, and delete projects and environments | ❌ | 🟢 |  |
| Move resources into or out of an environment | ❌ | 🟢 |  |
| Configure [protected environments](/docs/projects.md#protected-environments) and [cross-environment traffic blocking](/docs/projects.md#blocking-cross-environment-traffic) | ❌ | 🟢 |  |

### Environment groups

| Permission | Action | Read | Read &amp; write |
| --- | --- | --- | --- |
| Environment groups and their secret values | View environment groups and their secret values | 🟢 | 🟢 |
| Create, update, and delete environment groups | ❌ | 🟢 |  |
| Set environment group values | ❌ | 🟢 |  |
| Link and unlink environment groups to services | ❌ | 🟢 |  |

### Blueprints

| Permission | Action | Read | Read &amp; write |
| --- | --- | --- | --- |
| Blueprints | View Blueprint configuration | 🟢 | 🟢 |
| Update and disconnect Blueprints | ❌ | 🟢 |  |

### Audit logs

> *Want to view audit logs for every workspace in your org?*
>
> Create an [audit log API key](#audit-log-api-keys).

| Permission | Read |
| --- | --- |
| Read workspace audit logs | 🟢 |

## Audit log API keys

Audit log API keys have read-only access to [audit logs](/docs/audit-logs.md) for your organization and all of its workspaces.

[*Org Owners*](/docs/organizations.md#the-org-owner-role) can create an audit log API key by doing the following:

1. In the [Render Dashboard](https://dashboard.render.com), open the workspace dropdown at the top of the left pane and select your org.
2. Click *Settings* in the left pane and scroll down to the *Logs* section.
3. Under *Audit Log API Keys*, click *Create API key*:

   [image: The Audit Log API Keys section of an org's Settings page in the Render Dashboard]

4. Copy your new key. It's shown in full only once.

> *API keys are secret credentials!*
>
> Don't publicly post your API key, commit it to version control, or otherwise share it with anyone outside your organization.

## FAQ

###### What happens to my classic API keys?

*They continue to work as usual.* API keys you created before Render rolled out scoped API keys are called *classic* keys:

[image: A classic API key in the Render Dashboard]

They have the same permissions as your [member role](/docs/team-members.md#member-roles) in _every_ workspace you belong to.

To follow the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege), we recommend replacing your classic keys with scoped API keys.

###### Can scoped API keys access multiple workspaces?

*No.* Each scoped API key can only access the workspace you create it in.

###### What happens to an API key if my member role changes?

Your key's access adjusts to match your new [member role](/docs/team-members.md#member-roles).


---

##### Appendix: Glossary definitions

###### organization

Teams with a *Scale* plan or higher can manage multiple workspaces under a single unified org.

Orgs provide administrative features like SAML SSO and per-workspace access controls.

Related article: https://render.com/docs/organizations.md