---
issuer: https://darbsignal.com
authorization_server: https://darbsignal.com/.well-known/oauth-authorization-server
protected_resource: https://darbsignal.com/.well-known/oauth-protected-resource
register_uri: https://darbsignal.com/oauth/register
claim_uri: https://darbsignal.com/oauth/claim
revocation_uri: https://darbsignal.com/oauth/revoke
identity_types_supported:
  - anonymous
  - identity_assertion
  - service_auth
  - agent
  - user
  - service
credential_types_supported:
  - api_key
  - bearer_token
  - oauth2_client_credentials
flows_supported:
  - agent_verified
  - user_claimed
  - client_credentials
scopes_supported:
  - signals:read
  - darkpool:read
  - factor:read
  - alerts:write
mcp_server_card: https://darbsignal.com/.well-known/mcp/server-card.json
mcp_endpoint: https://darbsignal.com/mcp
agent_skills_index: https://darbsignal.com/.well-known/agent-skills/index.json
---

# Darbs Agent Authentication Guide (Auth.md)

This document provides machine-readable and human-verifiable instructions for autonomous AI agents, automated trading systems, and LLM runtimes to register and authenticate with Darbs Quantitative APIs.

* **Issuer:** `https://darbsignal.com`
* **Agent Skills Discovery Index (RFC v0.2.0):** `https://darbsignal.com/.well-known/agent-skills/index.json`
* **MCP Server Card (SEP-1649 / SEP-2127):** `https://darbsignal.com/.well-known/mcp/server-card.json`
* **Model Context Protocol Endpoint:** `https://darbsignal.com/mcp`
* **OAuth Authorization Server Metadata:** `https://darbsignal.com/.well-known/oauth-authorization-server`
* **OAuth Protected Resource Metadata (RFC 9728):** `https://darbsignal.com/.well-known/oauth-protected-resource`
* **OpenID Connect Discovery:** `https://darbsignal.com/.well-known/openid-configuration`
* **OpenAPI 3.1 Specification:** `https://darbsignal.com/docs/api/openapi.json`
* **API Documentation:** `https://darbsignal.com/docs/api`

---

## 1. Authentication Overview & Identity Types

Darbs supports structured agentic registration via the `auth.md` protocol and RFC 7591 dynamic registration.

### Supported Identity Types
* `anonymous`: Instant registration with pre-claim permissions, eligible for subsequent user binding.
* `identity_assertion`: Identity Provider ID-JAG assertion verified at registration time.
* `service_auth`: User-scoped service authorization bound through a verification/claim ceremony.
* `agent`: Autonomous software agent or browser LLM agent.
* `user`: Delegated interactive user authentication.
* `service`: Backend quant service or daemon.

### Supported Credential Types
* `api_key`: Long-lived institutional API token passed via `x-api-key`.
* `bearer_token`: Ephemeral JWT access token passed via `Authorization: Bearer <token>`.
* `oauth2_client_credentials`: OAuth 2.0 client ID and secret pair.

---

## 2. Supported Scopes

| Scope | Description |
| :--- | :--- |
| `signals:read` | Read real-time composite Darbs scores (0-100) and directional signals (LONG/SHORT/WAIT). |
| `darkpool:read` | Query institutional dark pool transaction prints and block trade aggregates. |
| `factor:read` | Access full 4-factor scoring breakdown (Social NLP, Tech Momentum, Valuation, Darkpool). |
| `alerts:write` | Register webhook endpoints for real-time volatility and signal shift alerts. |

---

## 3. Dynamic Agent Registration (`register_uri`)

Agents initiate autonomous registration by sending a `POST` request to `https://darbsignal.com/oauth/register`:

### Registration Request
```http
POST /oauth/register HTTP/1.1
Host: darbsignal.com
Content-Type: application/json

{
  "client_name": "AutonomousQuantAgent/1.0",
  "redirect_uris": ["https://agent.example.com/callback"],
  "grant_types": ["client_credentials", "refresh_token"],
  "response_types": ["token"],
  "scope": "signals:read darkpool:read factor:read",
  "token_endpoint_auth_method": "client_secret_post"
}
```

### Registration Response
```json
{
  "client_id": "drb_agent_9f83a2bc",
  "client_secret": "drb_sec_8841a024c6e91f",
  "client_id_issued_at": 1756382400,
  "client_secret_expires_at": 0,
  "grant_types": ["client_credentials", "refresh_token"],
  "scope": "signals:read darkpool:read factor:read",
  "registration_client_uri": "https://darbsignal.com/oauth/register/drb_agent_9f83a2bc"
}
```

---

## 4. Obtaining an Access Token (`token_endpoint`)

Exchange client credentials for an access token via `https://darbsignal.com/oauth/token`:

```http
POST /oauth/token HTTP/1.1
Host: darbsignal.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=drb_agent_9f83a2bc&client_secret=drb_sec_8841a024c6e91f&scope=signals:read%20darkpool:read
```

### Response
```json
{
  "access_token": "drb_tok_1756382400_a8f93e12",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "signals:read darkpool:read factor:read"
}
```

---

## 5. Calling Protected APIs

Pass the Bearer token in the `Authorization` header:

```http
GET /api/signals?symbol=NVDA HTTP/1.1
Host: darbsignal.com
Authorization: Bearer drb_tok_1756382400_a8f93e12
Accept: application/json
```

Or provide a valid institutional API key:

```http
GET /api/signals?symbol=NVDA HTTP/1.1
Host: darbsignal.com
x-api-key: drb_live_test_key_abc123
Accept: application/json
```

---

## 6. Claim Ceremony (`claim_uri`) & Revocation (`revocation_uri`)

### Claim Endpoint (`/oauth/claim`)
Binds an anonymous agent registration to an authenticated identity:
```http
POST /oauth/claim HTTP/1.1
Host: darbsignal.com
Authorization: Bearer drb_tok_1756382400_a8f93e12
Content-Type: application/json

{
  "agent_id": "drb_agent_9f83a2bc",
  "claim_code": "482910"
}
```

### Revocation Endpoint (`/oauth/revoke`)
Revokes issued agent credentials:
```http
POST /oauth/revoke HTTP/1.1
Host: darbsignal.com
Content-Type: application/x-www-form-urlencoded

token=drb_tok_1756382400_a8f93e12&token_type_hint=access_token
```

---

## 7. Sandbox Test Credentials

Immediate testing keys can be generated via `POST /api/apply` with payload `{"name":"Agent","email":"agent@example.com","focus":"quant"}`.