# auth.md

This document describes how AI agents can register, authenticate, and obtain
access tokens for the AlphaTrade (NexusTrade AI) API.

## Audience

This document is intended for autonomous AI agents and bot developers who need
to interact with the AlphaTrade API programmatically — including market data
analysis, portfolio management, and order execution.

## OAuth Protected Resource Metadata

AlphaTrade publishes OAuth Protected Resource Metadata (RFC 9728) at:

```
https://nexustrade-ai.base44.app/.well-known/oauth-protected-resource
```

This document declares the `resource` identifier, `authorization_servers`,
`scopes_supported`, and `bearer_token_methods` that agents need to obtain
access tokens.

## Authorization Server Metadata

The AlphaTrade authorization server metadata (RFC 8414) is published at:

```
https://nexustrade-ai.base44.app/.well-known/oauth-authorization-server
```

Agents should consult this document for the `issuer`, `token_endpoint`,
`registration_endpoint`, and `agent_auth` block with registration methods.

## Scopes

| Scope           | Description                                         |
|-----------------|-----------------------------------------------------|
| `read:market`   | Read market data, prices, and analysis signals      |
| `read:portfolio`| Read positions, balances, and portfolio state       |
| `write:orders`  | Create, modify, and cancel orders on behalf of user|
| `read:audit`    | Read decision audit trails and market snapshots     |
| `admin`         | Administrative access (user management, config)     |

## Registration Methods

AlphaTrade supports the following agent registration methods:

### 1. OAuth Dynamic Client Registration (RFC 7591)

Agents can register a client dynamically via the `register_uri` advertised in
the `agent_auth` block of the authorization server metadata.

```http
POST https://nexustrade-ai.base44.app/api/functions/agentRegister
Content-Type: application/json

{
  "client_name": "My Trading Agent",
  "client_uri": "https://my-agent.example.com",
  "scope": "read:market read:portfolio",
  "grant_types": ["client_credentials"],
  "token_endpoint_auth_method": "client_secret_post"
}
```

### 2. Verified Email Identity

Agents with a verified email identity can request a credential via the
`claim_uri` endpoint. The agent must prove control of the email address.

### 3. Anonymous (Limited Access)

Anonymous agents can access public market data endpoints with rate-limited
credentials issued via the `claim_uri` endpoint.

## Credential Use

Once registered, agents obtain a bearer token from the `token_endpoint` and
include it in the `Authorization` header:

```http
Authorization: Bearer <access_token>
```

Tokens are scoped to the permissions granted during registration. Agents
should respect `WWW-Authenticate` challenges on 401 responses, which include
a `resource_metadata` link pointing back to the PRM document.

## Revocation

Agents can revoke credentials via the `revocation_uri` advertised in the
authorization server metadata.

## Terms and Privacy

- [Terms of Service](https://nexustrade-ai.base44.app/contrato-de-uso)
- [Privacy Policy](https://nexustrade-ai.base44.app/politica-de-privacidade)
- [How It Works](https://nexustrade-ai.base44.app/como-funciona)