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

# Authentication: Sign In & API Keys

> Sign in to OneCLI Cloud and manage API keys for programmatic access. Learn the difference between project and org keys and how to rotate them.

oc handles authentication at two levels: **OneCLI auth** (your OneCLI instance) and **plugin auth** (service-specific credentials like Google OAuth tokens). OneCLI auth is the recommended path. Authenticate once, and oc fetches plugin credentials automatically.

## OneCLI authentication

### Log in

**Interactive** (opens browser):

```bash theme={null}
oc auth login --interactive
```

This starts a browser-based sign-in flow. Once you authenticate, oc stores your token in your OS keychain.

**Device flow** (for agents and headless environments):

```bash theme={null}
oc auth login
```

```json theme={null}
{
  "status": "auth_required",
  "url": "http://localhost:10254/auth/cli?code=abc123..."
}
```

The agent receives a URL to present to the user. Once the user authenticates in the browser, subsequent calls to oc will work.

**Direct token** (if you already have one):

```bash theme={null}
oc auth login <token>
```

```json theme={null}
{
  "status": "ok"
}
```

### Check auth status

```bash theme={null}
oc auth status
```

```json theme={null}
{
  "authenticated": true,
  "plugins": [
    {
      "name": "google",
      "has_credentials": true
    }
  ]
}
```

### Log out

```bash theme={null}
oc auth logout
```

This removes your stored token from the keychain.

## Plugin authentication

For plugins that support local auth, you can authenticate directly with the service:

```bash theme={null}
oc google auth
```

The plugin runs its own OAuth or device flow. oc captures the resulting credentials and stores them securely.

> [!TIP]
>
> Plugin auth commands are **meta-commands**: they run without requiring existing credentials. This lets you bootstrap auth from scratch.

## How credential resolution works

When you run a plugin command like `oc google calendar list-events`, oc resolves credentials in this order:

**1. Check for stored token**

oc looks for a stored token (from `oc auth login`). If found, it requests plugin credentials from your OneCLI instance.

**2. Fall back to local credentials**

If no token exists, oc checks for locally stored credentials (from `oc <plugin> auth`).

**3. Return an error with guidance**

If neither source has credentials, oc returns exit code `2` with an action hint:

```json theme={null}
{
  "error": "credentials required for 'google'",
  "code": "AUTH_REQUIRED",
  "action": "oc auth login"
}
```

## Credential storage and security

Credentials are stored using your OS keychain by default:

| Platform | Backend |
| - | - |
| macOS | Keychain |
| Windows | Credential Manager |
| Linux | Secret Service (D-Bus) |

If the keychain is unavailable, oc falls back to file-based storage at `~/.onecli/credentials/` with `0600` permissions (owner read/write only).

**What's stored where:**

| Item | Keychain key | File fallback |
| - | - | - |
| Auth token | `onecli-token` | `~/.onecli/credentials/token` |
| Plugin credentials | Plugin name | `~/.onecli/credentials/{plugin}.json` |

## Credential injection

When oc runs a plugin command, credentials are injected as environment variables. The plugin never reads credentials from files. It receives them from the parent process environment:

```
OC_GOOGLE_ACCESS_TOKEN=eyJ...
OC_GOOGLE_REFRESH_TOKEN=1//...
OC_GOOGLE_TOKEN_TYPE=Bearer
OC_GOOGLE_EXPIRES_AT=2025-01-01T00:00:00Z
```

The naming convention is `OC_{PLUGINNAME}_{FIELD}`, with the plugin name and field uppercased.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.