# Ezkielyna auth.md

How AI agents and developer tools get access to Ezkielyna.

## Audience

AI agents, coding tools and scripts that act for a person or a team with an Ezkielyna account.

## No credential needed

- MCP tools: `POST https://ezkielyna.store/mcp` (24 read-only tools)
- A2A model catalog agent: `POST https://ezkielyna.store/a2a`
- Discovery: `https://ezkielyna.store/.well-known/ai-catalog.json`, `https://ezkielyna.store/openapi.json`, `https://ezkielyna.store/llms.txt`

## Provisioning

A person must create the credential. Agents must not create accounts, make payments or accept terms on their own.

1. Buy API Credit at https://ezkielyna.store/api-credit
2. Create a key at https://api.ezkielyna.store/keys. The Auto group lets one key use the Standard, Premium and low-cost groups.
3. Give the key to the agent through an environment variable such as `EZK_API_KEY`.

## Agent sign-in with a person's approval

An agent can ask a person for a key with OAuth. The person must already have an Ezkielyna account linked to an API account with credit.

- Metadata: `https://ezkielyna.store/.well-known/oauth-authorization-server`
- Scope: `api`

### Authorization code with PKCE (MCP clients)

1. Register a public client: `POST https://ezkielyna.store/api/store/agent/oauth/register` with `client_name` and `redirect_uris` (https, http on loopback, or an app scheme). No client secret is issued.
2. Send the person to `https://ezkielyna.store/oauth/authorize` with `response_type=code`, `client_id`, `redirect_uri`, `code_challenge`, `code_challenge_method=S256`, `state`, and optionally `scope` and `resource=https://ezkielyna.store/mcp/api`.
3. After the person approves, `POST https://ezkielyna.store/api/store/agent/oauth/token` with `grant_type=authorization_code`, `code`, `code_verifier`, `client_id` and `redirect_uri`. A code works once and ends after 5 minutes.

### Device flow

Public client id: `ezkielyna-third-party` (no client secret).

1. `POST https://ezkielyna.store/api/store/agent/device/code` with `client_id`, `scope` and an optional short `device_name`.
2. Show the person `verification_uri` and `user_code`. The person signs in, compares the code and decides. Never approve for them.
3. Every `interval` seconds, `POST https://ezkielyna.store/api/store/agent/device/token` with `grant_type=urn:ietf:params:oauth:grant-type:device_code`, `device_code` and `client_id`. Handle `authorization_pending`, `slow_down`, `access_denied` and `expired_token`.
4. On success you receive `access_token`, `token_type`, `expires_in`, `scope` and `base_url`. Show the token to nobody and do not log it.

The token is an API key of its own. It spends the person's API Credit up to 5 USD, ends after 30 days and can be revoked at any time at https://ezkielyna.store/account#agent-devices. An account can hold 5 active agent keys. The agent name is shown to the person as unverified.

Refresh tokens are not issued: when a key ends, ask the person again. Agents cannot create accounts, buy credit or approve their own request.

## Supported methods

- OAuth 2.0 authorization code with PKCE and the device flow, described above
- API key as a Bearer token: `Authorization: Bearer <key>`
- API key in `x-api-key`, for `/v1/messages` only

## Using the credential

- OpenAI format: base URL `https://api.ezkielyna.store/v1`
- Anthropic format: base URL `https://api.ezkielyna.store`
- MCP tools that use your key: `POST https://ezkielyna.store/mcp/api` with the Bearer token
- List the models a key can use: `GET https://api.ezkielyna.store/v1/models`

Keep the key out of URLs, logs, client-side code and shared files. A `401` means the key is missing or not valid. A `429` means wait and try again.

Delete a key on the API Keys page to revoke it. Keys from the device flow are revoked on the account page. Full documentation: https://api.ezkielyna.store/docs/
