> For the complete documentation index, see [llms.txt](https://docs.silkline.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.silkline.ai/profile-and-settings/organization-settings/api-keys.md).

# API Keys

Create, scope, and delete the API keys your integrations use to authenticate against the Silkline GraphQL API

API keys let external systems authenticate against the [Silkline API](https://docs.silkline.ai/administration-tools/api.md) on behalf of your organization. Each key is a named `clientId` and `clientSecret` pair. It can read your organization's data; its selected permissions control writes.

The **API keys** tab is located under **Organization Settings → General** at `/dashboard/organization/settings/api-keys`.

## Enabling API keys

{% hint style="info" %}
**Silkline Admin Only:** API keys are enabled per organization by Silkline. Until enabled, the API keys tab shows a feature card. Contact <support@silkline.ai> to enable it for your organization.
{% endhint %}

## Permissions

Three permissions control key management. The **Admin** role holds all three by default; assign them to other roles in [Users and Access](https://docs.silkline.ai/profile-and-settings/organization-settings/organization-users.md) under **Access Control**.

| Permission         | Allows                                  |
| ------------------ | --------------------------------------- |
| **Create API Key** | Create a new key and receive its secret |
| **Edit API Key**   | Change a key's write permissions        |
| **Delete API Key** | Delete a key                            |

Every organization member can view the list of keys. The client secret is never shown in the list.

## Creating a key

{% stepper %}
{% step %}

### Open the API keys tab

Go to **Organization Settings → API keys** and click **Create API key**.
{% endstep %}

{% step %}

### Name the key

Give the key a name that identifies the system using it (for example, `Power BI reporting` or `ERP order sync`). Names must be unique among the organization's active keys.
{% endstep %}

{% step %}

### Choose write permissions

Leave every permission unselected for read-only access. For an integration that writes data, select only the resource actions it needs, then create the key.
{% endstep %}

{% step %}

### Copy the credentials

The `clientId` and `clientSecret` are shown once. Copy the secret into your secret manager before leaving the page. It cannot be viewed again; if it is lost, create a new key and delete the old one.
{% endstep %}
{% endstepper %}

## Access

Keys with no grants cannot insert, update, or delete records through GraphQL table mutations. Granted keys can write only through supported permission gates.

API sessions cannot write contacts, order workflows, followers, shares, saved queries, snippets, table views, browser sessions/profiles, bulk imports, integration ID mappings, or user records, even with every permission selected. Approval-step writes require an applicable permission; an API key cannot act as a user approver or delegate.

Open a key's detail page to change its selected permissions and save. Check the required operations before connecting an integration.

## Replacing a key

To change a key's credentials — when a secret may have been exposed, when the person who held it leaves, or on your organization's regular schedule — create a new key, update the consuming system with its `clientId` and `clientSecret`, then delete the old key.

## Deleting a key

Deleting a key removes it permanently.

1. Open the key's row and click **Delete**.
2. Type the key's name to confirm.

A deleted key cannot obtain tokens or access organization records through GraphQL, including with a previously issued token. A deleted key cannot be restored; create a new key instead. The organization's audit log keeps the record of the key and of the changes made with it.

## Best practices

* **One key per integration.** Give each external system its own named key so it can be replaced or deleted without affecting other systems, and so its activity can be attributed.
* **Grant only required writes.** Start with no permissions for reporting, and add only the supported actions an integration needs.
* **Replace keys on personnel change.** Replace every key a departing team member could have accessed, and replace a key immediately on any suspected exposure.
* **Store secrets in a secret manager.** Never commit a `clientSecret` to source control or paste it into chat or email.
* **Review the list regularly.** Delete keys for integrations that are no longer in use.
