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

# API Keys

> Create and manage API keys from the SalesOS Dashboard.

# API Key Management

<Tip>
  Once you have a key, try signed requests in your browser at the [API Sandbox](https://play2sellsa.github.io/api-sandbox/) — paste the API key and secret, and the playground signs requests automatically.
</Tip>

API keys let your integrations authenticate with SalesOS using the [P2S-SIGN-V1](/api/authentication) signed-request scheme. Keys are created and managed exclusively through the SalesOS Dashboard.

<Info>
  API key management requires the **admin.integrations** capability. Tenant owners and admins have this by default.
</Info>

***

## Create a key

<Steps>
  <Step title="Open the Dashboard">
    Go to [dashboard.play2sell.com](https://dashboard.play2sell.com) (or [staging](https://dashboard-staging.play2sell.com)) and log in with your admin account.
  </Step>

  <Step title="Navigate to API Keys">
    Go to **Integrations > API Keys** in the sidebar menu.
  </Step>

  <Step title="Create a new key">
    Click **Create API Key** and fill in:

    * **Name** — A descriptive name (e.g., "CRM Nightly Sync", "Website Forms")
    * **Scope** — Select `default:sync` for standard integrations
    * **Rate limit** — Requests per hour (default: 1,000)
    * **Expiration** — Optional expiry date
  </Step>

  <Step title="Copy both values">
    After creation, the Dashboard displays **two values, only once**:

    * **API Key** — the public identifier, e.g. `sk_live_a1b2c3d4...`. Sent in the `Authorization` header on every signed request.
    * **API Key Secret** — used to compute the request signature. Never sent over the wire.

    Copy both immediately and store them securely (environment variables, secrets manager).
  </Step>
</Steps>

<Warning>
  The **API Key Secret** is shown **only once** at creation time. If you lose it, revoke the key and create a new one — there is no way to recover the secret.
</Warning>

***

## Manage existing keys

The same **Integrations > API Keys** screen lets you:

* **View** all active, revoked, and expired keys (the secret is never displayed again)
* **Revoke** a key — immediately stops it from working, preserving audit history
* **Delete** a key — permanently removes it (prefer revoking)
* **Monitor usage** — see request count and last-used date

***

## Available scopes

| Scope          | Grants access to                                     |
| -------------- | ---------------------------------------------------- |
| `default:sync` | `sync_collaborators` and `sync_activities` endpoints |
| `leads:read`   | Read lead data                                       |
| `leads:write`  | Create and update leads                              |

<Note>
  An empty `scopes` selection means the key has **no scope restriction** — it can access any endpoint that accepts API key auth.
</Note>

***

## Best practices

<AccordionGroup>
  <Accordion title="Use multiple keys for different integrations">
    Create separate keys for each integration (CRM sync, website forms, partner API). This way, if one key is compromised, you only need to rotate that one.
  </Accordion>

  <Accordion title="Set expiration dates">
    Keys without expiration live forever. Set an expiry to enforce regular rotation — 90 days is a good default.
  </Accordion>

  <Accordion title="Use minimal scopes">
    If a key only needs to sync activities, give it `default:sync` only. Don't leave scopes empty unless the key truly needs full access.
  </Accordion>

  <Accordion title="Monitor usage">
    Check the request count and last-used date on the Dashboard list. Keys that haven't been used in months may be candidates for revocation.
  </Accordion>

  <Accordion title="Rotate keys without downtime">
    1. Create a new key in the Dashboard
    2. Update your integration to use the new key + secret
    3. Verify the new key works
    4. Revoke the old key
  </Accordion>
</AccordionGroup>

***

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="shield" href="/api/authentication">
    Learn the P2S-SIGN-V1 signing scheme with code samples
  </Card>

  <Card title="Activities Integration" icon="plug" href="/api/integrations/activities">
    Start sending activities with your new key
  </Card>
</CardGroup>