> ## 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.

# Authentication

> Authenticate API requests with an ek_live_ token or a short-lived JWT.

Every Enkryptify API request must be authenticated. You have two options:

1. **Use an `ek_live_` token directly**: the simplest path. Recommended for most workloads.
2. **Exchange it for a JWT**: recommended only for very high request rates.

## Get an API token

Create a token from the [Credentials page](https://app.enkryptify.com) in your dashboard. Tokens start with `ek_live_` and are shown only once at creation. Store the value in your CI provider's secret storage (GitHub Actions secrets, GitLab CI variables, etc.). Never commit it to source.

See [API tokens](/credentials/api-tokens) for full guidance on rotation, scoping and revocation.

## Option 1: Use the token directly

Pass the token in the `Authorization` header on every request:

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

This is the right choice for almost every use case. The API caches token validation, so latency is low.

## Option 2: Exchange for a JWT

For very high request volumes, exchange the token once for a 15-minute JWT and reuse it. The JWT is validated statelessly with no database hit per request.

### Exchange

```bash theme={"dark"}
curl -X POST https://api.enkryptify.com/v1/auth/exchange \
  -H "Authorization: Bearer ek_live_xxxxx"
```

Response:

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

### Use the JWT

Send the JWT in the `Authorization` header for subsequent calls:

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

When `expiresIn` runs out, exchange again. The exchange endpoint is rate-limited to 10 requests per minute per token, so cache the JWT. Don't exchange on every request.

## Scopes and permissions

Tokens carry the permissions you set when you created them:

* **Permission**: `read` or `read-write`. Write operations are rejected for read-only tokens.
* **Scope**: full workspace or limited to specific teams / projects / environments.

The effective permission for any request is the intersection of:

* the token's permission and scope, and
* the underlying user's workspace role.

## SDK

The [Enkryptify SDK](https://github.com/Enkryptify/sdk) handles the JWT exchange and refresh for you:

```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",
});
```