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

# Authentication

> Install the codika CLI, authenticate with API keys, manage multiple profiles, and switch between organizations

> **Agents / terminal-only setups:** if you have email access but no browser, use the [CLI OTP auth flow](./cli-auth) — two commands per signup or login, and a `cko_` key lands in `~/.config/codika/config.json` automatically. This page covers dashboard-paste login and profile management.

## When to use

* First-time environment setup (with a key already minted from the dashboard)
* When deploy or project commands fail with "API key is required"
* To check current identity or switch between organizations
* When the user needs to authenticate with a different org
* For OTP-based self-provisioning from an AI agent, see [CLI OTP auth](./cli-auth) first

## Prerequisites

* Node.js 22+ installed
* npm available

## Install the CLI

```bash theme={null}
# Install globally
npm install -g codika

# Verify installation
codika --version
```

***

## login

Save an API key and create a named profile. Alias for `config set`.

```bash theme={null}
codika login [options]
```

### Options

| Option             | Description                                                 |
| ------------------ | ----------------------------------------------------------- |
| `--api-key <key>`  | API key (skips interactive prompt)                          |
| `--base-url <url>` | Base URL override (defaults to production)                  |
| `--name <name>`    | Custom profile name (auto-derived from org name if omitted) |
| `--skip-verify`    | Save without verifying the key against the API              |

### Behavior

1. Prompts for API key (masked input) unless `--api-key` is provided
2. Validates the key against the Codika platform API (unless `--skip-verify`)
3. Stores profile metadata: org ID, org name, key name, scopes, creation date, expiry date
4. Sets the new profile as active

### Examples

```bash theme={null}
# Interactive login
codika login

# Non-interactive login
codika login --api-key cko_abc123def456

# Login with custom profile name
codika login --api-key cko_abc123def456 --name staging

# Login to a custom environment
codika login --api-key cko_abc123def456 --base-url https://custom.api.example.com
```

***

## whoami

Show the current authenticated identity.

```bash theme={null}
codika whoami [options]
```

### Options

| Option   | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

### Behavior

Validates against the platform API for fresh data. Falls back to cached profile data if the network call fails.

### Output

```
Organization:  Acme Corp
Key name:      production-key
Key:           cko_abc...xyz
Scopes:        deploy:use-case, workflows:trigger
Expires:       2026-12-31
Profile:       acme-corp
```

***

## use

Switch the active profile or list all profiles.

```bash theme={null}
codika use [name]
```

### Arguments

| Argument | Description                                                      |
| -------- | ---------------------------------------------------------------- |
| `[name]` | Profile name to switch to (optional — lists profiles if omitted) |

### Options

| Option   | Description                                       |
| -------- | ------------------------------------------------- |
| `--json` | Output machine-readable JSON with profile details |

### Behavior

* **No argument**: Lists all profiles with an active marker (bullet)
* **With argument**: Switches the active profile

### Output (list mode)

```
  ● acme-corp      (Acme Corp)
    staging         (Acme Corp - Staging)
    other-org       (Other Organization)
```

### JSON output

When called with `--json`, outputs an array of profile objects — useful for agents to match `project.json` `organizationId` to the correct profile:

```bash theme={null}
codika use --json
```

```json theme={null}
[
  {
    "name": "acme-corp",
    "organizationId": "org_abc123",
    "organizationName": "Acme Corp",
    "scopes": ["deploy:use-case", "workflows:trigger"],
    "keyPrefix": "cko_abc",
    "active": true
  },
  {
    "name": "staging",
    "organizationId": "org_abc123",
    "organizationName": "Acme Corp - Staging",
    "scopes": ["deploy:use-case"],
    "keyPrefix": "cko_def",
    "active": false
  }
]
```

### Examples

```bash theme={null}
# List all profiles
codika use

# Switch to a specific profile
codika use staging
```

***

## logout

Remove a profile.

```bash theme={null}
codika logout [name]
```

### Arguments

| Argument | Description                                         |
| -------- | --------------------------------------------------- |
| `[name]` | Profile name to remove (defaults to active profile) |

### Behavior

Removes the specified profile. If it was the active profile, switches to the next available profile.

***

## config set

Save API key and base URL. Same as `login`.

```bash theme={null}
codika config set [options]
```

Options are identical to `login`.

## config show

Display all stored profiles.

```bash theme={null}
codika config show
```

### Output

```
Profiles:
  ● acme-corp       cko_abc...xyz  (Acme Corp)
    staging          cko_def...uvw  (Acme Corp - Staging)
```

Exit code 0 if profiles exist, 1 if none.

## config clear

Remove configuration.

```bash theme={null}
codika config clear [options]
```

### Options

| Option             | Description                                      |
| ------------------ | ------------------------------------------------ |
| `--profile <name>` | Remove only this profile (clears all if omitted) |

### Examples

```bash theme={null}
# Clear a specific profile
codika config clear --profile staging

# Clear all profiles and configuration
codika config clear
```

***

## Configuration storage

| Item        | Location                                       |
| ----------- | ---------------------------------------------- |
| Config file | `~/.config/codika/config.json`                 |
| Permissions | `0o600` (owner read/write only)                |
| Format      | Multi-profile JSON with active profile pointer |

## API key resolution priority

1. `--api-key` / `--api-url` flag on any command
2. `CODIKA_API_KEY` / `CODIKA_BASE_URL` environment variable
3. Active profile in config file
4. Production default (base URL only)

## Organization-aware profile selection

When `project.json` in a use case folder contains an `organizationId`, the CLI automatically selects the matching profile for deployment commands — even if a different profile is currently active.

## Error reference

| Error                   | Cause                                | Fix                                              |
| ----------------------- | ------------------------------------ | ------------------------------------------------ |
| "API key is required"   | No key provided or found             | Run `codika login`                               |
| "Invalid API key"       | Key is wrong or expired              | Check with `codika whoami`, re-login             |
| "EACCES" on npm install | Permission denied                    | Use `sudo npm install -g` or fix npm permissions |
| Wrong org on deploy     | Active profile doesn't match project | Use `codika use <correct-profile>`               |