# Midkernel auth.md

Canonical authentication instructions: https://www.midkernel.com/security/app/auth.md

Midkernel uses Google sign-in and explicit human consent to connect a service
agent to an existing account and workspace. Registration alone grants no access
and creates no account, workspace, credits, or scans.

## Public agent access

Agents can read public Threat Intel without registration, an account, an API key,
or credits. Connect a Streamable HTTP MCP client to:

https://www.midkernel.com/security/app/mcp/threat-intel

Select no authentication. Available read tools are ti_sources, ti_classes,
ti_daily_report, ti_latest, ti_trends, and ti_get. Discover their current inputs
with tools/list. Send tool calls sequentially and honor HTTP Retry-After on 429.

Public usage skill: https://www.midkernel.com/.well-known/agent-skills/midkernel-threat-intel/SKILL.md

## Discovery and exact resource selection

The authorization server issuer is exactly https://www.midkernel.com/security/app.
Use these published metadata documents to discover the live contract:

- Authorization server: https://www.midkernel.com/.well-known/oauth-authorization-server/security/app
- Default service resource: https://www.midkernel.com
- Origin protected-resource metadata: https://www.midkernel.com/.well-known/oauth-protected-resource
- Canonical MCP resource: https://www.midkernel.com/security/app/mcp
- MCP protected-resource metadata (RFC 9728 path insertion): https://www.midkernel.com/.well-known/oauth-protected-resource/security/app/mcp
- Agent registration (register_uri / identity_endpoint): POST https://www.midkernel.com/security/app/api/agent/identity
- Claim ceremony renewal (claim_uri / claim_endpoint): POST https://www.midkernel.com/security/app/api/agent/identity/claim
- Token exchange: POST https://www.midkernel.com/security/app/api/oauth/token
- Human consent: https://www.midkernel.com/security/app/oauth/claim
- Manage and revoke agent access: https://www.midkernel.com/security/app/oauth/agents

Select exactly one resource per grant. Agent registration defaults to the origin
service, which includes protected Scan REST, Threat Intel REST, and MCP endpoints
under https://www.midkernel.com/security/app. Existing authorization-code clients default to the
canonical MCP resource. These identifiers are exact and cannot be exchanged or
refreshed into one another. Keep the selected resource throughout the grant.

Root protected-resource discovery returns HTTP 200 with resource https://www.midkernel.com.
The path-specific document retains resource https://www.midkernel.com/security/app/mcp. The public homepage
requires no token; the origin identifier represents the app's protected service.
The root authorization-server URL https://www.midkernel.com/.well-known/oauth-authorization-server
keeps its HTTP 307 referral to https://www.midkernel.com/.well-known/oauth-authorization-server/security/app. Follow that referral and
validate the exact issuer and selected resource; it does not create a root issuer.

## Register a service agent

Send application/json to https://www.midkernel.com/security/app/api/agent/identity:

```json
{"type":"service_auth","login_hint":"person@example.com","client_name":"My research agent","scope":"threat-intel:read","resource":"https://www.midkernel.com"}
```

The legacy verified_email compatibility request is also supported:

```json
{"type":"identity_assertion","assertion_type":"verified_email","assertion":"person@example.com","client_name":"My research agent"}
```

Both formats start the same Google consent ceremony. An email hint is never
identity proof. There is no email OTP endpoint. The signed-in Google account
must have that verified email and an active Midkernel membership. Anonymous
credentials, JWT-bearer assertion exchange, ID-JAG, and provider-event
registration are unsupported. The metadata's identity_assertion request format
does not mean this service issues an identity assertion.

The response contains registration_id, registration_type service_auth, a private
claim_token and its expiration, post_claim_scopes, the selected resource, and a
claim object with user_code, verification_uri, expires_in, and interval. The
pending ceremony lasts ten minutes. Keep claim_token private; never send it to
the human or place it in a URL. Open verification_uri for the human and show
user_code separately. The URL contains an opaque claim-attempt token and never
the code. The human signs in with Google, checks the workspace, agent name and
scopes, enters the separate code, then explicitly approves or denies.

## Obtain the approved access token

Poll https://www.midkernel.com/security/app/api/oauth/token using application/x-www-form-urlencoded, at most once
every five seconds. Use the resource selected at registration:

```text
grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=PRIVATE_CLAIM_TOKEN&resource=https%3A%2F%2Fwww.midkernel.com
```

Before approval the response is authorization_pending. Excessive polling returns
slow_down; denial returns access_denied; an expired ceremony returns expired_token.
After approval a single successful exchange returns access_token, token_type
Bearer, expires_in 3600, and the approved scope. Claim exchange is single use.
This claim-only profile issues neither an identity assertion nor a refresh token.
Re-register and obtain fresh human consent when the one-hour access token expires.

If a pending ceremony needs a new link or code, POST application/json containing
claim_token and email to https://www.midkernel.com/security/app/api/agent/identity/claim. The same private claim
token and email hint are required. Renewal invalidates the previous link and
code and never extends the original expiration. At most three renewals are
allowed, separated by thirty seconds after the first. An expired request requires
registration again.

## Permissions, spending, and revocation

threat-intel:read is the default. It permits read-only Threat Intel REST and the
corresponding authenticated MCP tools and spends no Scan credits. Request scan
explicitly for hosted Scan, or both scopes separated by a space. The human must
approve the requested scopes; normal workspace permissions and credit limits
still apply. Consent itself never starts a scan.

Hosted Scan requires a Midkernel account, repository authorization through the
read-only GitHub App, and prepaid credits. Calling the MCP start_run tool debits
credits immediately and has no separate quote or confirmation step. Reading this
document or using the public Threat Intel skill does not start a Scan or buy
credits. Obtain explicit user authorization before initiating a paid run.

Send access tokens only as Authorization: Bearer ACCESS_TOKEN to the intended
protected service, such as https://www.midkernel.com/security/app/api/threat-intel/evidence,
https://www.midkernel.com/security/app/api/scans/start for approved scan access, or https://www.midkernel.com/security/app/mcp.
Never put tokens in URLs or public metadata. Public Threat Intel needs no token.

The account holder can revoke access at https://www.midkernel.com/security/app/oauth/agents. Every
authenticated agent request checks the stored grant, issuer, audience, scope,
expiry, authority epoch, and live membership. Revoked grants, removed membership,
and disabled accounts fail closed. Agent permissions exclude organization
credential management, invitations, and platform administration, including when
the approving account is an administrator. Never paste access tokens, claim tokens, or
claim URLs into logs, issues, or chat.

## Existing OAuth client connection

Authorization code with PKCE S256 and refresh_token remain supported for existing
OAuth clients. These are separate from the claim-only profile above. The public
client flow advertises token_endpoint_auth_methods_supported: ["none"]. Use a
browser for sign-in and consent, and verify the authorization response's issuer
parameter against https://www.midkernel.com/security/app.

- Authorization endpoint: https://www.midkernel.com/security/app/oauth/authorize
- Token endpoint: https://www.midkernel.com/security/app/api/oauth/token
- Dynamic Client Registration endpoint: https://www.midkernel.com/security/app/api/oauth/register

The server supports Client ID Metadata Documents (CIMD): a compatible client can
identify itself with its HTTPS client metadata document URL. OAuth Dynamic
Client Registration (DCR) instead registers client metadata at the advertised
registration endpoint. These identify an OAuth client and create no Midkernel
account. Choose exactly one supported resource, obtain user consent, and keep
that resource bound through authorization, token exchange, and refresh.

Documentation: https://www.midkernel.com/security/docs/mcp
Pricing: https://www.midkernel.com/security/pricing
Terms: https://www.midkernel.com/legal/terms