# Authentication

> Use an account-wide API key or approve an application in the browser.

## Two Ways To Connect

Every Model API request sends one Bearer credential:

```http
Authorization: Bearer <api-key-or-application-access-token>
```

Use an **API Key** for a script, server, or unattended workload. Use **Sign In
with Makojima** for a registered application that can open a browser. An invalid
credential fails without falling back to website sign-in or another token type.

## API Keys

Create and manage account-wide keys on **Developers**. At creation you
choose **7 Days**, **30 Days**, **90 Days**, **Custom Date**, or **Never**. The
server default is **90 Days**, and expiration cannot be changed later.

Key names are unique within an account, including names belonging to expired or
revoked keys. **Rename** changes only the display name. **Rotate Key** replaces
the secret immediately while preserving the key record and expiration. **Revoke
Key** permanently stops the key.

New keys are one continuous string of **48 letters and digits** (`A–Z`, `a–z`,
and `0–9`). They are case-sensitive and contain no punctuation, spaces, or
`mk_` prefix. The key list shows only the first four characters. Previously
issued account keys remain usable until they expire, are revoked, or are
rotated; rotation issues the current format.

The complete secret appears only after creation or rotation. Makojima stores a
four-character preview, a keyed verification value, and management metadata.
There is no reveal or recovery endpoint.

## Sign In With Makojima

Makojima initially registers applications through operator-controlled tooling.
Public clients do not contain a client secret. They use Authorization Code with
S256 PKCE and an exact registered callback.

```mermaid
sequenceDiagram
    participant App
    participant Browser
    participant Site as Makojima
    participant API as Model API
    App->>Browser: Open authorization with state and S256 PKCE
    Browser->>Site: Sign in and review Model Access
    Browser->>Site: Approve or Deny
    Site-->>App: Return a single-use code and state
    App->>Site: Exchange code and PKCE verifier
    Site-->>App: Access token and rotating refresh token
    App->>API: Send Bearer access token
```

Discovery is available at:

```text
https://makojima.com/.well-known/oauth-authorization-server
```

The authorization, token, and revocation addresses come from that document.
Clients must use the discovered exact values and validate the returned `state`.

The Model Access permission covers minimal account identity, available models,
credit balance, inference, and the application’s permitted requests. It does
not permit key management, password changes, settings, purchases, training,
publishing, or another application’s requests.

## Sessions Stay Connected

Application access tokens last 15 minutes. The person does not sign in every
15 minutes and does not sign in merely because the application closed. The
application stores the current access and refresh credentials in an operating
system credential store, reloads them on startup, and rotates the refresh token
when renewal is needed.

The connection has no fixed overall expiration. It ends when the person revokes
the application, the application signs out that installation, the password is
changed or reset, account access ends, or refresh-token replay invalidates the
installation.

## Revoke Access

**Developers → Connected Applications → Revoke Access** stops every
installation of the selected application for that account. An application’s own
Sign Out revokes its current installation. A password change or reset invalidates
all application grants, sessions, refresh credentials, and pending login codes,
then requires fresh browser approval.

API keys are managed separately and are not silently revoked by an application
sign-out or password change.

## Keep Credentials Safe

Use the operating system credential store for a native client, VS Code
SecretStorage for an extension, or a server secret store. Never put API keys,
access tokens, refresh tokens, or authorization codes in URLs, source control,
terminal arguments, browser storage, analytics, or logs.

Two-factor authentication is strongly recommended for the Makojima account. It
does not replace key expiration, protected client storage, rotation, revocation,
or activity review.