---
title: "Authentication"
description: "Documentation for Authentication in ZeyOS SDK CLI"
canonical_url: "https://www.zeyos.com/sdk/authentication"
markdown_url: "https://www.zeyos.com/ai/guide/sdk/authentication.md"
section: "sdk"
authority: "guide"
language: "en"
source_repository: "zeyos/sdk-v2"
source_path: "docs/authentication/index.md"
source_revision: "a99897af74253b4dc5af6fecb9301cea0ae18e27"
---

# Authentication

The SDK accepts credentials from environment variables or from its saved host store. A local app link records the active instance in `.zeysdk`, while saved host credentials are global to the user account.

## 1. Environment Variables (Recommended for CI/CD)

Environment variables are the recommended method for CI/CD environments and automated workflows.

```bash
# Set environment variables
ZEYSDK_TOKEN=your_token
ZEYSDK_SERVER=https://cloud.zeyos.com/your_instance

# Run commands
zeysdk [command]
```

`ZEYSDK_TOKEN` overrides token lookup. `ZEYSDK_SERVER` overrides the active sync URL for commands that load sync data, including `run` and `compile`, and is also consumed by `zeysdk link`. Set both for portable non-interactive execution; a server-only override still needs a matching saved token for the active instance and URL.

### Platform-Specific Commands

**Windows CMD:**
```cmd
set ZEYSDK_TOKEN=your_token && set ZEYSDK_SERVER=https://cloud.zeyos.com/your_instance && zeysdk [command]
```

**Windows PowerShell:**
```powershell
$env:ZEYSDK_TOKEN="your_token"; $env:ZEYSDK_SERVER="https://cloud.zeyos.com/your_instance"; zeysdk [command]
```

**Linux/macOS:**
```bash
export ZEYSDK_TOKEN=your_token && export ZEYSDK_SERVER=https://cloud.zeyos.com/your_instance && zeysdk [command]
```

## 2. Stored Credentials (Default for local development)

For local development, link an application once and let the SDK reuse the saved instance-and-URL credential.

```bash
# Link your instance first
zeysdk link

# Then run commands
zeysdk [command]
```

## Authentication and URL Priority

For `zeysdk link`, explicit `--token` and `--url` flags take precedence over `ZEYSDK_TOKEN` and `ZEYSDK_SERVER`. The resulting values then take precedence over a saved host or an interactive prompt.

For commands operating on an existing link:

1. A non-empty `ZEYSDK_SERVER` replaces the URL from `.zeysdk/sync.json`.
2. A non-empty `ZEYSDK_TOKEN` replaces the saved token.
3. Without `ZEYSDK_TOKEN`, the SDK looks up a saved credential for the active instance and effective URL. Legacy instance-only entries are used only when their stored URL matches the effective URL; otherwise relink the instance or provide explicit environment credentials.

`zeysdk bundle install` deliberately requires `--token` and `--url` together when either flag is used.

## Credential Storage

Choose the backend interactively with `zeysdk configure` → `Credential Storage`:

| Mode | Behavior |
|------|----------|
| `Auto` | Uses the OS keyring on supported desktop systems. WSL and headless Linux use the file store; an unavailable desktop keyring may also fall back to it. |
| `OS Keyring` | Requires the platform keyring and reports an error when it cannot be used. |
| `File Store` | Stores credentials unencrypted in `~/.config/zeysdk/store.json` with owner-only file permissions. |

The storage preference is written to `~/.config/zeysdk/settings.json`. When the keyring is used, `~/.config/zeysdk/account-index.json` tracks account names so the CLI can enumerate configured hosts; tokens remain in the keyring.

`ZEYSDK_USE_KEYRING` overrides the saved mode. Values `1`, `true`, or `yes` select the keyring; other values select the file store. `ZEYSDK_USE_KEYTAR` is accepted as a legacy alias when the newer variable is unset.

## Expired Tokens

When most wrapped commands receive a `401`, the CLI can prompt once for a replacement token, validate the relink, update the saved credential, and retry the original command once. `link` reports its own authentication failure instead of recursively relinking, and `migrate` does not perform the automatic retry.

## Security Notes

- Stored credentials can use the OS keyring or the unencrypted file store
- Environment-variable lifetime depends on how the shell or CI system defines them
- Stored credentials persist between sessions
- Use environment variables for CI/CD to avoid storing credentials
- Use stored credentials for local development convenience
- Avoid putting tokens directly into shared scripts, command history, logs, or bundle files

## Error Handling

| Error | Description | Resolution |
|-------|-------------|------------|
| Missing token | No authentication provided for the active instance and effective URL | Set both environment variables, add a matching host, or run `zeysdk link` |
| Invalid token | Bad credentials | Check token validity |
| Server error | Invalid server URL | Verify server URL format |
| Keyring unavailable | Explicit keyring backend cannot be opened | Repair keyring access or select `Auto`/`File Store` |
| Network error | Connection failed | Check connectivity |