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

# API tokens

> Create static tokens for CI/CD pipelines, scripts and programmatic access.

API tokens are long-lived credentials that let your applications authenticate with the Enkryptify API. Each token starts with `ek_live_` and works as a Bearer token.

## When to use API tokens

* **CI/CD pipelines** — inject secrets into GitHub Actions, GitLab CI, Jenkins or any build system
* **Scripts and automation** — fetch secrets from cron jobs, deployment scripts or infrastructure tools
* **Servers and VMs** — any deployed process that needs secrets at runtime
* **Local development** — the CLI creates short-lived tokens automatically when you run `ek login`, but you can create longer-lived tokens for shared tooling

## Token types

Enkryptify has two token types:

| Type       | Created by                 | Lifetime             | Use case                |
| ---------- | -------------------------- | -------------------- | ----------------------- |
| **Static** | You, from the dashboard    | 24 hours to 6 months | CI/CD, scripts, servers |
| **CLI**    | The CLI, during `ek login` | 8 hours              | Local development       |

CLI tokens are created automatically and scoped to a single environment. The rest of this page covers static tokens.

## Creating a token

<Steps>
  <Step title="Open the Credentials page">
    Navigate to **Credentials** in the sidebar.
  </Step>

  <Step title="Start creation">
    Click **"Create credential"**.
  </Step>

  <Step title="Configure the token">
    Fill in the form:

    * **Name** — a label to identify this token (e.g. `github-actions-prod`, `deploy-script`)
    * **Permission** — `Read only` or `Read & Write`. Use read-only unless your workflow needs to create or update secrets
    * **Scope** — toggle off "Full workspace access" to restrict the token to specific teams, projects or environments
    * **Expiration** — how long the token is valid (24 hours to 6 months)
  </Step>

  <Step title="Copy the token">
    After creation, the raw token is displayed **once**. Copy it immediately and store it in your CI/CD provider's secret storage (e.g. GitHub Actions secrets, GitLab CI variables).

    <Warning>
      The token value cannot be retrieved after you close this dialog. If you lose it, revoke the token and create a new one.
    </Warning>
  </Step>
</Steps>

## Using a token

### Exchange for a JWT

API tokens are not used directly for API calls. Instead, you exchange the token for a short-lived JWT:

```bash theme={"dark"}
curl -X POST https://api.enkryptify.com/v1/auth/exchange \
  -H "Content-Type: application/json" \
  -d '{"token": "ek_live_..."}'
```

Response:

```json theme={"dark"}
{
  "accessToken": "eyJhbG...",
  "expiresIn": 900,
  "tokenType": "Bearer"
}
```

### Use the JWT

Use the JWT as a Bearer token for all API calls:

```bash theme={"dark"}
curl https://api.enkryptify.com/v1/secrets/... \
  -H "Authorization: Bearer eyJhbG..."
```

The JWT is valid for 15 minutes. When it expires, exchange the token again.

### SDK usage

The Enkryptify SDK handles the exchange and refresh automatically:

```typescript theme={"dark"}
import { Enkryptify } from "@enkryptify/sdk";

const client = new Enkryptify({
  token: process.env.ENKRYPTIFY_TOKEN, // your ek_live_* token
});

const secrets = await client.getSecrets({
  project: "my-project",
  environment: "production",
});
```

## Rotating a token

Rotation generates a new token value while keeping the same name, permission and scope. The old token is immediately revoked.

1. Go to **Credentials**
2. Click the actions menu (three dots) on the token row
3. Click **Rotate**
4. Copy the new token value (shown once, same as during creation)

Use rotation when you suspect a token may have been exposed, or as part of a regular credential rotation policy.

## Revoking a token

Revoking a token invalidates it immediately. Any application using the token will lose access within 15 minutes (when the current JWT expires).

1. Go to **Credentials**
2. Click the actions menu on the token row
3. Click **Revoke**
4. Confirm the revocation

<Note>
  Revocation cannot be undone. You will need to create a new token if you need access again.
</Note>

## CI/CD examples

### GitHub Actions

Store the token as a repository or organization secret, then use it in your workflow:

```yaml theme={"dark"}
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Fetch secrets
        env:
          ENKRYPTIFY_TOKEN: ${{ secrets.ENKRYPTIFY_TOKEN }}
        run: |
          # The SDK or CLI handles the token exchange automatically
          npx @enkryptify/sdk pull --project my-project --env production
```

### GitLab CI

Add the token as a CI/CD variable (masked and protected), then reference it in your pipeline:

```yaml theme={"dark"}
deploy:
  script:
    - npx @enkryptify/sdk pull --project my-project --env production
  variables:
    ENKRYPTIFY_TOKEN: $ENKRYPTIFY_TOKEN
```

## Best practices

* **Use the shortest expiration that works.** A deploy script that runs daily doesn't need a 6-month token.
* **One token per use case.** Don't share a token across unrelated pipelines. If one is compromised, you can revoke it without affecting others.
* **Scope tokens narrowly.** A production deploy token should only have access to the production environment, not the entire workspace.
* **Use read-only unless you need write.** Most CI/CD pipelines only need to read secrets.
* **Store tokens in your CI provider's secret storage.** Never commit tokens to source code or configuration files.
* **Rotate tokens regularly.** Set a reminder to rotate long-lived tokens every 30-60 days.