---
name: Dataware Ltd Agent Authentication & Registration
register_uri: https://datawareltd.ca/api/v1/agent/register
oauth_protected_resource: https://datawareltd.ca/.well-known/oauth-protected-resource
oauth_authorization_server: https://datawareltd.ca/.well-known/oauth-authorization-server
supported_identity_types:
  - ai_agent
  - service_account
  - user_delegated
supported_credential_types:
  - client_credentials
  - bearer_token
  - api_key
---

# Agent Authentication & Authorization Specification (Auth.md)

This document provides machine-readable and human-readable instructions for autonomous AI agents, LLMs, and automated clients to register, authenticate, and interact with the **Dataware Ltd** API platform (`datawareltd.ca`).

---

## 1. Discovery Metadata

- **OAuth 2.0 Authorization Server**: `https://datawareltd.ca/.well-known/oauth-authorization-server`
- **OAuth Protected Resource**: `https://datawareltd.ca/.well-known/oauth-protected-resource`
- **OpenID Connect Discovery**: `https://datawareltd.ca/.well-known/openid-configuration`
- **MCP Server Card**: `https://datawareltd.ca/.well-known/mcp/server-card.json`
- **Agent Skills Index**: `https://datawareltd.ca/.well-known/agent-skills/index.json`
- **API Catalog**: `https://datawareltd.ca/.well-known/api-catalog`

---

## 2. Dynamic Agent Registration

Autonomous AI agents can register programmatically using the OAuth 2.0 Dynamic Client Registration protocol or the dedicated agent registration endpoint.

```http
POST /api/v1/agent/register HTTP/1.1
Host: datawareltd.ca
Content-Type: application/json

{
  "client_name": "Autonomous-Dataware-Agent",
  "grant_types": ["client_credentials", "authorization_code"],
  "response_types": ["code"],
  "scope": "read:analytics execute:queries book:demo hms:access",
  "agent_metadata": {
    "agent_type": "ai_agent",
    "developer_email": "agent-ops@datawareltd.ca"
  }
}
```

### Registration Response
```json
{
  "client_id": "agent_dw_9204820192",
  "client_secret": "sec_dw928490a84f...",
  "client_id_issued_at": 1722260000,
  "client_secret_expires_at": 0,
  "grant_types": ["client_credentials"],
  "token_endpoint_auth_method": "client_secret_basic"
}
```

---

## 3. Obtaining Access Tokens (Client Credentials Grant)

```http
POST /oauth/token HTTP/1.1
Host: datawareltd.ca
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(client_id:client_secret)>

grant_type=client_credentials&scope=read:analytics+execute:queries
```

### Token Response
```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:analytics execute:queries"
}
```

---

## 4. Protected Resource Authentication

Include the Bearer token in the `Authorization` HTTP header on all API requests:

```http
GET /api/v1/dashboards/overview HTTP/1.1
Host: datawareltd.ca
Authorization: Bearer <access_token>
Accept: application/json
```

---

## 5. Supported Scopes

| Scope Name | Description |
| :--- | :--- |
| `read:analytics` | Read access to enterprise BI dashboards and metrics. |
| `execute:queries` | Execution access for automated Big Data query pipelines. |
| `book:demo` | Permission to submit demo bookings on behalf of enterprise clients. |
| `hms:access` | API access for Hospital Management System modules. |

---

## 6. Revocation & Introspection

- **Token Revocation**: `https://datawareltd.ca/oauth/revoke`
- **Token Introspection**: `https://datawareltd.ca/oauth/introspect`