# auth.md

## Linkality Auth and API Posture

Linkality is in public beta. Access uses Linkality accounts, scoped API keys, and bearer authentication for the hosted MCP/REST runtime.

## Agent registration

### Discovery

Agent registration metadata is available at:

https://linkality.com/auth.md

https://linkality.com/.well-known/oauth-protected-resource

https://linkality.com/.well-known/oauth-authorization-server

### Registration method

Manual public beta registration.

### Register URI

https://linkality.com/contact

### Identity endpoint

https://linkality.com/contact

### Claim endpoint

https://linkality.com/contact

### Revocation endpoint

https://linkality.com/contact

### Supported identity types

* workspace_user
* approved_agent
* service_auth
* manual_public_beta

### Supported credential types

* scoped_api_key
* bearer_token

### Supported scopes

* actions:propose
* actions:simulate
* ledger:read
* approvals:read
* policies:read

### Registration steps

1. Fetch https://linkality.com/auth.md
2. Fetch https://linkality.com/.well-known/oauth-protected-resource
3. Fetch https://linkality.com/.well-known/oauth-authorization-server
4. Review the `agent_auth` metadata.
5. Request public beta agent registration at https://linkality.com/contact
6. Provide workspace, agent name, intended connector types, and requested scopes.
7. Store issued credentials outside prompts, logs, screenshots, issue comments, and source control.
8. Use only approved scopes.
9. Use simulation before sensitive actions.
10. Respect `APPROVAL_REQUIRED` decisions.
11. Request credential revocation or rotation through https://linkality.com/contact

### Not currently supported

* public OAuth dynamic client registration
* public OIDC issuer metadata
* automatic ID-JAG verification
* automatic JWT-bearer token exchange
* unrestricted self-serve agent onboarding
* unrestricted agent execution

## Current auth model

- Browser users authenticate through the Linkality app.
- Agent clients use scoped Linkality API keys where supported.
- MCP clients send `Authorization: Bearer <token>` to the hosted MCP endpoint.
- API keys should be stored outside prompts and never committed.

## OAuth/OIDC posture

Linkality does not currently advertise a public OAuth authorization server or public OIDC issuer for third-party dynamic client registration. The OAuth/OIDC well-known endpoints return truthful limited JSON instead of fake metadata.

## Scopes

Representative scopes include actions:propose, actions:simulate, ledger:read, approvals:read, policies:read, and connector-specific scopes. Governance/admin scopes are not granted casually to agent keys.

## Approval-required workflow

If a tool returns APPROVAL_REQUIRED, the agent must wait for a human decision. Poll with linkality_get_decision or direct the human to the Linkality app. Do not fabricate approval and do not proceed while pending.

## Signed receipt verification

Use linkality_get_receipt to export a receipt for a governed action. Verify integrity by recomputing the canonical SHA-256 hash. Verify origin only when a signature validates against a trusted public key. The public verifier page is https://linkality.com/verify.

## Safety boundaries

- Do not put secrets, tokens, private keys, connection strings, customer data, or private schemas into prompts.
- Do not expose private workspace routes through public discovery.
- Do not treat approval as permission for a different action.
- Do not claim live broker execution unless it is configured, certified, and safe for that workspace.
- Agents must not place secrets in prompts, logs, screenshots, issue comments, or public repos.
- Agent registration should request the minimum required scopes.
- Human approval may be required for sensitive actions.
- Credentials are revocable.
- Approval-required flows must be respected.

## Registration metadata

```json
{
  "service": "Linkality",
  "auth_md_version": "0.1",
  "registration_supported": true,
  "registration_mode": "manual_public_beta",
  "skill": "https://linkality.com/auth.md",
  "register_uri": "https://linkality.com/contact",
  "claim_uri": "https://linkality.com/contact",
  "revocation_uri": "https://linkality.com/contact",
  "credential_types_supported": ["scoped_api_key", "bearer_token"],
  "identity_types_supported": ["workspace_user", "approved_agent", "service_auth", "manual_public_beta"],
  "identity_flows_supported": ["manual_public_beta"],
  "dynamic_client_registration_supported": false,
  "oauth_authorization_server_public": false,
  "oidc_issuer_public": false,
  "authorization_servers": ["https://linkality.com"],
  "scopes_supported": [
    "actions:propose",
    "actions:simulate",
    "ledger:read",
    "approvals:read",
    "policies:read"
  ],
  "agent_auth": {
    "skill": "https://linkality.com/auth.md",
    "auth_md": "https://linkality.com/auth.md",
    "registration_supported": true,
    "registration_mode": "manual_public_beta",
    "registration_method": "manual_public_beta",
    "register_uri": "https://linkality.com/contact",
    "identity_endpoint": "https://linkality.com/contact",
    "claim_endpoint": "https://linkality.com/contact",
    "revocation_endpoint": "https://linkality.com/contact",
    "credential_types_supported": ["scoped_api_key", "bearer_token"],
    "identity_types_supported": ["workspace_user", "approved_agent", "service_auth", "manual_public_beta"],
    "grant_types_supported": ["manual_public_beta"],
    "scopes_supported": ["actions:propose", "actions:simulate", "ledger:read", "approvals:read", "policies:read"],
    "dynamic_client_registration_supported": false,
    "notes": "Linkality supports manual public beta agent registration with scoped credentials. Public OAuth dynamic client registration, public OIDC issuer metadata, automatic ID-JAG verification, and automatic JWT-bearer token exchange are not generally available."
  },
  "agent_requirements": [
    "store credentials outside prompts, logs, screenshots, issue comments, and source control",
    "request least-privilege scopes",
    "respect APPROVAL_REQUIRED decisions",
    "never fabricate approvals",
    "use simulation before sensitive actions",
    "request revocation or rotation through /contact"
  ]
}
```

Support: hello@linkality.com