# Organization API Keys





Organization API keys let you deploy and manage sites programmatically — ideal for CI/CD pipelines, scripts, and automation.

Key format [#key-format]

Organization API keys use the `org_` prefix:

```
org_abc123def456...
```

This prefix distinguishes them from personal API keys and automatically scopes all operations to the organization.

Who can create keys [#who-can-create-keys]

Only **owners** and **admins** can create and revoke organization API keys. Members cannot manage keys.

Creating a key [#creating-a-key]

1. Navigate to your organization's **Keys** page
2. Click **Create Key**
3. Copy the key immediately — it won't be shown again

<Callout type="warn">
  Store your API key securely. It cannot be retrieved after creation. If you lose it, revoke it and
  create a new one.
</Callout>

Using in CI/CD [#using-in-cicd]

Set your organization API key as an environment variable. The CLI detects the `org_` prefix and automatically scopes deploys to the correct organization.

GitHub Actions [#github-actions]

```yaml
name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      SAMPLEX_API_KEY: ${{ secrets.ORG_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build
      - run: npx samplex deploy ./dist
```

Other CI providers [#other-ci-providers]

Set `SAMPLEX_API_KEY` as a secret environment variable in your CI provider's settings, then run `npx samplex deploy ./dist` in your pipeline.

Permission scopes [#permission-scopes]

Organization API keys have access to these operations:

| Scope         | Description                              |
| ------------- | ---------------------------------------- |
| `site:read`   | View site details and metadata           |
| `site:deploy` | Deploy new sites or update existing ones |
| `site:delete` | Delete sites from the organization       |
| `site:list`   | List all sites in the organization       |

Rate limiting [#rate-limiting]

Organization API keys are rate-limited to **120 requests per 5 minutes**. If you exceed this limit, requests return a `429 Too Many Requests` response.

Finding your Organization ID [#finding-your-organization-id]

Your Organization ID is displayed at the top of the **Keys** page in your organization dashboard. You need this ID when using the CLI with the `--org` flag.

Revoking keys [#revoking-keys]

1. Go to the **Keys** page
2. Find the key you want to revoke
3. Click **Revoke**

Revoked keys stop working immediately. Any CI/CD pipelines using the key will fail until updated with a new key.