---
slug: auth
title: "Authentication: OAuth and API keys"
description: "OAuth has the system authenticate for you; an API key binds authentication to the key itself. Which client uses which, and the minimum key hygiene."
lang: en
---


# Authentication: OAuth and API keys

Before an AI can attach to your memory, something has to confirm **that this is
you**. Not just anyone gets to read and write someone else's memory. There are
two ways to do that confirmation. **OAuth** and an **API key**. The difference
comes down to one sentence.

> **OAuth has the system authenticate on your behalf. An API key binds
> authentication into a single key.**

## OAuth: approve once with your account and you're done

Add AiAkiv in an AI app and a **sign-in window** appears. Approve once with your
AiAkiv account and from then on **the system verifies your identity by itself.**

- Identity is **bound to your account.** You're authenticated as *you*, not as
  the app.
- **No secret ends up in your hands.** Nothing to copy, nothing to manage.
- **The system handles renewal and revocation.** Clean up on the account side and
  access is cleaned up with it.

## API key: authentication bound into the key

You issue a key in the console and paste it into the app's settings. There's no
sign-in window. Instead, **the key itself is the ID card.**

- **Whoever holds the key is you.** App or person, the key alone grants your
  access.
- So a key must be handled with **the same weight as a password** (see [Key
  hygiene](#key-hygiene) below).
- Issuing and revoking is **on you**: *API key management* in the console
  ([Console](console)).

The console can issue two kinds.

| Key | Where it saves | What it's for |
|----|-----------|------|
| **Dynamic key** | Follows the current **save target (Main)** | Change Main in the console and this key's save location moves with it |
| **Project key** | **Pinned to one project** | Reads and writes only that project: for pinning a target per folder or per app |

## Which to use: OAuth by default

**If your client supports OAuth, use OAuth without thinking about it.** There's
no secret to manage, and it follows your account policy directly.

| Method | Clients |
|------|-----------|
| **OAuth (recommended)** | Claude Web · Claude Desktop · Claude Code · **ChatGPT classic** · Cursor · Grok |
| **API key (the only setup)** | Gemini CLI · **ChatGPT** · Antigravity |

> **⚠ ChatGPT and ChatGPT classic are different apps.** The names are similar and
> both get installed, but the setup is the opposite. **classic uses an OAuth
> connector**, while **ChatGPT can't use OAuth at all.** Start by checking which
> one you opened → [Connecting ChatGPT](chatgpt).

For the bottom three this is **not a choice.** But the reason it's key-only
differs per app.

| Client | Why key-only |
|---|---|
| **Gemini CLI** | The OAuth sign-in session doesn't persist |
| **ChatGPT** | OAuth doesn't attach: not via a custom connector, not via headers |
| **Antigravity** | There's one config for the whole app, so it can't be split per folder: which means **the key** picks the project |

For per-client setup, follow the [setup guide](https://www.aiakiv.com/setup).

## Key hygiene

Since the key is your identity, leaking it means **handing over access to your
memory itself.** Below is the minimum.

- **It's shown once, at issue time.** Move it somewhere safe then (a password
  manager). You cannot view it again.
- **Issuing a new key for the same target automatically retires the old one.** So
  **re-issuing is revoking**: if you suspect a leak, just issue a new one.
- **Don't share it.** Not into chat, issues, or documents. Not to an AI either.
- **Don't commit it.** If a key lives in a config file, exclude that file from
  commits (`.gitignore`).
- **A key can't exceed your own permissions.** Its access ceiling is your team
  role, a read-only person's key doesn't gain write access.
- And don't **store keys inside memories** in the first place → [What to
  store](what-to-store).

## Common confusions

- **"It's OAuth: why does changing project ask me to sign in again?"** Some
  OAuth clients (Claude Code, Cursor) need re-authentication when the save target
  changes. That's normal.
- **"I pasted a key and saving goes somewhere unexpected."** A dynamic key
  **follows Main.** To pin the target, use a project key or set up folder binding
  ([Folder binding](folder-binding) · [Teams and
  projects](teams-and-projects)).
- **"I lost my key."** There's no recovery. **Issue a new one**: the old key is
  retired and you carry on with the new one.

## Next

- Installation and per-client setup → [Quickstart](quickstart)
- Where saving goes (teams and projects) → [Teams and projects](teams-and-projects)
- What not to store → [What to store](what-to-store)
- *API key management* in the console → [Console](console)