# APort auth.md

This file explains how agents and service clients authenticate to APort.
APort currently uses scoped API keys and user sessions. It does not yet publish
a full OAuth authorization server for third-party token exchange.

## Discover

Use these discovery resources first:

- API catalog: `https://aport.io/.well-known/api-catalog`
- OpenAPI: `https://aport.io/api/openapi-json`

APort currently supports service credentials through scoped API keys and bearer
tokens. API keys are the recommended server-to-server credential for policy
verification and audit persistence.

## Pick a method

Use `X-API-Key: apk_...` for service-to-service calls. Some clients may also use
`Authorization: Bearer apk_...`; `X-API-Key` is preferred because it is explicit
and avoids confusion with user JWT sessions.

Use a user session token only for browser/dashboard operations initiated by a
signed-in human.

## Register

Human users can create an organization and issue API keys from the APort
dashboard. Teams in a pilot can ask APort to create an org, enable a bounded
pilot, and invite members.

No-login passport issuance is available through `https://aport.id/api/issue` for
agent identity creation. Runtime guardrails can then use the returned passport
identifier and, when available, the setup key.

## Claim

Passports issued through `aport.id` may require a human claim step by email.
Only the human owner should complete the claim. Agents should not attempt to
claim ownership for themselves.

## Exchange

For the current APort API, there is no OAuth token exchange required for API-key
service calls. Send the API key directly in the `X-API-Key` header.

The agent_auth terms used by discovery clients are:

- `agent_auth`
- `identity_endpoint`
- `identity_assertion`
- `service_auth`
- `id-jag`

APort may add a full agent-auth identity exchange later. Until then, agents
should follow the API-key path documented here.

## Use the access_token

For API keys, treat the key as the access token:

```http
POST https://aport.io/api/verify/policy/system.command.execute.v1
X-API-Key: apk_...
Content-Type: application/json
```

Include only the policy context needed for the decision. Do not send secrets,
private file contents, or unnecessary personal data.

## Errors

APort API errors are JSON objects with an error code and message when handled by
the API. Common classes are:

- `401 unauthorized`: missing, invalid, expired, or unsupported credential.
- `403 forbidden`: valid credential without the required scope or resource access.
- `404 not_found`: endpoint or resource not found.
- `429 rate_limited`: retry after the indicated window.
- `500 internal_server_error`: unexpected server failure.

When a protected endpoint returns `401`, agents should read the JSON error body
and use this guide plus `/api.md` to choose an API-key or bearer-token flow.
APort does not currently advertise OAuth protected-resource metadata through an
HTTP authentication challenge.

## Revocation

Revoke API keys in the APort dashboard or through admin tooling. Rotate keys if
they are exposed in logs, local files, CI output, or chat transcripts. Remove
keys from old repositories and developer machines when a pilot ends.

## Scopes

APort API keys currently use this accepted scope vocabulary:

- `read`: read passports and metadata available to the credential owner. Hosted
  policy verification currently requires this scope.
- `issue`: issue passports through supported issuance endpoints.
- `update`: update passports where the credential owner is authorized.
- `status`: update passport status where authorized.
- `list_agents`: list agent records exposed to the credential owner.
- `read_audit`: read audit records exposed to the credential owner.
- `manage_webhooks`: manage webhook endpoints.
- `manage_keys`: create and manage org API keys where authorized.

Do not request undocumented scopes such as `verify`, `write`, or `admin`; the
API rejects unsupported scope names.