> ## Documentation Index
> Fetch the complete documentation index at: https://api.onlysocial.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace API keys

> Issue the osk_ key your integration uses inside a customer's workspace, without anybody opening the dashboard.

Your integration talks to a customer's workspace through the normal workspace APIs ([Messaging](https://api.onlysocial.io/messaging/account/get-the-authenticated-workspace.md), [Publishing](https://api.onlysocial.io/publishing/diagnostics/check-your-key.md), [Link in Bio](https://api.onlysocial.io/biolinks/overview.md) and [webhooks](https://api.onlysocial.io/webhooks/manage.md)), with a workspace API key. You can issue that key yourself for any workspace you provisioned.

```bash theme={null}
curl -X POST https://app.onlysocial.io/api/partner/workspaces/$WORKSPACE/api-keys \
  -H "X-API-KEY: $PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dealer CRM",
    "scopes": ["salesbot:contacts:read", "salesbot:contacts:write"],
    "expires_at": null
  }'
```

| Field | | |
| - | - | - |
| `name` | required | Up to 80 characters, so the customer can recognise it. |
| `scopes` | required | At least one [permission](https://api.onlysocial.io/authentication.md#permissions). |
| `expires_at` | optional | A future date and time, or `null` for no expiry. |

```json 201 theme={null}
{
  "success": true,
  "message": "API key created. The token is shown once and cannot be retrieved again.",
  "data": {
    "id": "0b8d6f4e-....",
    "name": "Dealer CRM",
    "prefix": "osk_3fA9",
    "scopes": ["salesbot:contacts:read", "salesbot:contacts:write"],
    "created_at": "2026-10-20T09:15:40+00:00",
    "expires_at": null,
    "revoked_at": null,
    "last_used_at": { "publishing": null, "salesbot": null, "biolinks": null },
    "plain_text_token": "osk_3fA9…"
  }
}
```

> [!WARNING]
>
> `plain_text_token` is returned **once**. It is stored as a hash and cannot be shown again. Put it straight into your secret store, and keep the response body out of your logs (it is sent with `Cache-Control: no-store`).

## Rules

* **Same permissions as the dashboard.** `scopes` takes the same list a workspace admin sees. A permission the workspace cannot have, for a feature its plan does not include, is a `422`, never silently dropped.
* **25 live keys per workspace**, shared with keys made in the dashboard. Revoke an unused one before creating another.
* **The key acts as the customer's admin.** It is attributed to the workspace admin you provisioned, and stops working if that person stops being an admin.
* **Audited.** Every key you issue is written to the customer's audit log, naming your partner account.

## List and revoke

* `GET /api/partner/workspaces/{workspace}/api-keys` lists the workspace's keys: name, prefix, scopes, dates and last use per API. Never the secret.
* `DELETE /api/partner/workspaces/{workspace}/api-keys/{id}` revokes a key immediately, for every API. Repeating it returns `200`, so retries are safe.

A workspace that is not yours, or does not exist, is a `404`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.