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

All requests to the [Render API](/docs/api.md) must authenticate using an API key. 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](/docs/api-keys.md#permissions).
   - You can also set permissions for _all workspace resources_ at once:

     [image: Buttons to change the permissions for all resource types at once in the API key creation form]

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

5. Click *Generate API key*. Your key is shown in full only once:

   [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](/docs/api-keys.md#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](/docs/api-keys.md#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 key permissions

To change an existing 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.

> 🟢 Permitted
>
> ❌ Not permitted
>
> *N/A* Access level not offered for this permission

### Services

#### Web and private services, static sites, background workers, and cron jobs

| Action | Read | Write | Read & write |
| --- | --- | --- | --- |
| View services and their configuration | 🟢 | N/A | 🟢 |
| Create, update, and delete services | ❌ | N/A | 🟢 |
| Manage preview environments and one-off jobs | ❌ | N/A | 🟢 |

#### Environment variables and secret files

| Action | Read | Write | Read & write |
| --- | --- | --- | --- |
| View environment variables and secret files | 🟢 | ❌ | 🟢 |
| Set environment variable and secret file values | ❌ | 🟢 | 🟢 |

### Workflows

#### Workflows

| Action | Read | Write | Read & write | Run |
| --- | --- | --- | --- | --- |
| View workflows, versions, and task-run inputs and results | 🟢 | N/A | 🟢 | N/A |
| Create, update, and delete workflows, and create versions | ❌ | N/A | 🟢 | N/A |

#### Workflow secrets

| Action | Read | Write | Read & write | Run |
| --- | --- | --- | --- | --- |
| View workflow environment variables and secret files | 🟢 | ❌ | 🟢 | N/A |
| Set workflow environment variable and secret file values | ❌ | 🟢 | 🟢 | N/A |

#### Run workflow tasks

| Action | Read | Write | Read & write | Run |
| --- | --- | --- | --- | --- |
| Trigger and cancel task runs and flow runs | N/A | N/A | N/A | 🟢 |

### Sandboxes

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

#### Sandbox lifecycle and snapshots

| Action | Read | Write | Read & write | Execute |
| --- | --- | --- | --- | --- |
| View sandboxes, sandbox groups, and snapshots | 🟢 | N/A | 🟢 | N/A |
| View execution history and credential settings | 🟢 | N/A | 🟢 | N/A |
| Create and terminate sandboxes | ❌ | N/A | 🟢 | N/A |
| Create, update, and delete sandbox groups | ❌ | N/A | 🟢 | N/A |
| Create and delete snapshots | ❌ | N/A | 🟢 | N/A |

#### Sandbox execution and file transfer

| Action | Read | Write | Read & write | Execute |
| --- | --- | --- | --- | --- |
| Run commands in sandboxes | N/A | N/A | N/A | 🟢 |
| Upload and download files | N/A | N/A | N/A | 🟢 |

#### Manage sandbox credentials

| Action | Read | Write | Read & write | Execute |
| --- | --- | --- | --- | --- |
| Create, update, and delete credentials | N/A | 🟢 | N/A | N/A |

### Deploys

#### Deployment information

| Action | Read | Run |
| --- | --- | --- |
| View deploys, their status, and history | 🟢 | 🟢 |

#### Run deployments

| Action | Read | Run |
| --- | --- | --- |
| Trigger and cancel deploys | ❌ | 🟢 |
| Trigger [rollbacks](/docs/rollbacks.md) | ❌ | 🟢 |

### Monitoring

#### Read resource logs, metrics, events, and export settings

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

### Postgres

#### Postgres instances

| Action | Read | Write | Read & write |
| --- | --- | --- | --- |
| View databases and their configuration | 🟢 | N/A | 🟢 |
| Create, update, and delete databases | ❌ | N/A | 🟢 |

#### Postgres credentials and connection details

| Action | Read | Write | Read & write |
| --- | --- | --- | --- |
| View connection strings and credentials | 🟢 | ❌ | 🟢 |
| Create and delete database credentials | ❌ | 🟢 | 🟢 |

#### Postgres exports and backups

| Action | Read | Write | Read & write |
| --- | --- | --- | --- |
| View and download exports and backups | 🟢 | N/A | 🟢 |
| Create exports and backups | ❌ | N/A | 🟢 |

### Key Value

#### Key Value instances

| Action | Read | Read & write |
| --- | --- | --- |
| View instances and their configuration | 🟢 | 🟢 |
| Create, update, and delete instances | ❌ | 🟢 |

#### Read Key Value connection details

| Action | Read | Read & write |
| --- | --- | --- |
| View connection URLs and credentials | 🟢 | N/A |

### Object storage

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

#### Objects and blobs

| Action | Read | Read & write |
| --- | --- | --- |
| 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.

#### Build sources and builds

| Action | Read | Write | Read & write |
| --- | --- | --- | --- |
| View build sources, their configuration, and their builds | 🟢 | N/A | 🟢 |
| Create, update, and delete build sources | ❌ | N/A | 🟢 |
| Trigger builds | ❌ | N/A | 🟢 |

#### Build-source environment variables and secret files

| Action | Read | Write | Read & write |
| --- | --- | --- | --- |
| View build-source environment variables and secret files | 🟢 | ❌ | 🟢 |
| Set build-source environment variable and secret file values | ❌ | 🟢 | 🟢 |

### Workspaces

#### Members, notifications, webhooks, and log and metric streams

| Action | Read | Read & write |
| --- | --- | --- |
| 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

#### Projects and environments

| Action | Read | Read & write |
| --- | --- | --- |
| 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

#### Environment groups

| Action | Read | Write | Read & write |
| --- | --- | --- | --- |
| View environment groups | 🟢 | N/A | 🟢 |
| Create, update, and delete environment groups | ❌ | N/A | 🟢 |

#### Environment group variables and secret files

| Action | Read | Write | Read & write |
| --- | --- | --- | --- |
| View environment group variable and secret file values | 🟢 | ❌ | 🟢 |
| Set environment group variable and secret file values | ❌ | 🟢 | 🟢 |

### Blueprints

#### Blueprints

| Action | Read | Read & write |
| --- | --- | --- |
| 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