Authentication

Two Ways To Connect

Every Model API request sends one Bearer credential:

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 under Developer Access. 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.

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:

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

Developer Access → 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.