> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# API Key

An API Key is an authentication method used to invoke the [Cresc API](https://api.cresc.dev/openapi) within CI/CD pipelines or automated scripts. Compared to standard username/password logins, API Keys are much more secure and easier to manage.

## Use Cases

- **Continuous Integration/Deployment (CI/CD)**: Automate OTA update publishing via GitHub Actions, GitLab CI, Jenkins, etc.
- **Automation Scripts**: Write scripts to manage apps, versions, or native packages in bulk.
- **Third-Party Integrations**: Wrap Cresc's workflows into external developer tools.

## Creating an API Key

1. Log into the [Cresc Dashboard](https://admin.cresc.dev)
2. Click on "API Key" in the left sidebar menu.
3. Click the "Create API Key" button.
4. Enter a name for the API Key (e.g., CI/CD Pipeline).
5. Select the required permissions.
6. (Optional) Set an expiration date.
7. Click Create, and **copy the secret API Key immediately**.

:::warning
The API Key string is only displayed once upon creation. You will not be able to view it again. Be sure to save it safely immediately!
:::

## Permissions

| Permission | Description                                                      |
| ---------- | ---------------------------------------------------------------- |
| **Read**   | View app details, version info, and native package details       |
| **Write**  | Create/Update apps, publish new versions, upload native packages |
| **Delete** | Delete apps, versions, and packages                              |

:::info
You must select at least one permission when creating a API Key. Applying the principle of least privilege is a best practice.
:::

## Using API Key with API

When calling the Cresc API, supply the API Key via the `x-api-token` HTTP header:

```bash
curl -X GET "https://api.cresc.dev/app/list" \
  -H "x-api-token: YOUR_API_TOKEN"
```

:::info
The header `x-api-token` and the environment variable `CRESC_API_TOKEN` are wire-level names kept unchanged for compatibility with existing integrations. The console and the docs call it an API Key — they are the same thing.
:::

### Using in the CLI

If you're using the `react-native-update-cli` tool (v2.7.0+), you can pass the API Key via environment variables:

```bash
export CRESC_API_TOKEN=your_api_token_here
cresc bundle --platform android
```

### Using in CI/CD Environments

Here is an example configuring a GitHub Action:

```yaml
# .github/workflows/publish.yml
name: Publish Hot Update

on:
  push:
    branches: [main]

jobs:
  publish:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        platform: [ios, android]
    steps:
      - uses: actions/checkout@v6

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 22

      - name: Install dependencies
        run: npm ci && npm i -g react-native-update-cli

      - name: Bundle, publish and bind
        env:
          CRESC_API_TOKEN: ${{ secrets.CRESC_API_TOKEN }}
        run: |
          cresc bundle --platform ${{ matrix.platform }} \
            --name "${GITHUB_SHA::7}" \
            --description "OTA ${GITHUB_SHA::7}" \
            --packageVersionRange ">=1.0.0 <2.0.0" \
            --rollout 10
```

:::warning
CI has no interactive terminal, so the CLI runs non-interactively and skips the "publish?" and "bind?" prompts. Without `--name` it only builds the bundle, and without a binding option (`--packageVersionRange`, `--packageVersion`, `--packageId`, `--minPackageVersion` or `--maxPackageVersion`) the version is published but **no users receive it**. Commit `update.json` so CI can resolve the app, and set `--packageVersionRange` to the native versions that should get this update. `--rollout` is optional (1–100, default 100). See [CLI Tools](/docs/cli.md#cresc-bundle).
:::

:::tip
In CI/CD pipelines, always store your API Key securely using the platform's Secret Manager (e.g., GitHub Secrets) rather than hardcoding them in your configuration scripts.
:::

## Managing API Key

### Viewing API Key List

On the "API Key" page, you can view all created API Key, including:

- API Key Name
- Permissions
- Expiration Time
- Last Used Time
- Status (Active/Expired/Revoked)

### Revoking a API Key

If a API Key is leaked or no longer needed, you can revoke it at any time:

1. Identify the API Key in the table list.
2. Click the "Revoke" button.
3. Confirm revocation.

:::warning
Revocations take effect immediately. Any API requests made using a revoked API Key will be instantly rejected. Ensure you update any dependent CI/CD setups before revoking.
:::

## Security Practices

1. **Principle of Least Privilege**: Only grant the exact permissions required.
2. **Set Expirations**: Try to use short-lived API Key or configure expirations for temporary integration projects.
3. **Periodic Rotation**: Routinely revoke old API Key and cycle in new API Key for long-running workflows.
4. **Secure Storage**: Never commit API Key directly to your repository source code.
5. **Monitor Usage**: Check the 'Last Used Time' and delete idle API Key routinely.

## Limits

- Each user can create a maximum of **10** API Keys.
- To create additional API Key, you must first revoke existing unused API Key.

## Related

- [Automating React Native OTA Updates in CI/CD](/react-native-ota-ci-cd.md) — full GitHub Actions, Fastlane, and GitLab CI pipelines with native-diff guards
- [CLI Tools](/docs/cli.md) — full flag reference for `cresc bundle`, `cresc publish`, and `cresc update`
- [Publishing Hot Updates](/docs/publish.md) — baseline uploads, version ranges, and gradual rollouts
- [CodePush CLI migration](/codepush-api-migration.md#5-cli-mapping) and [Expo Updates CLI migration](/expo-updates-migration.md#5-map-eas-update-cli-and-expo-router-entry-point)