# ProximaHub auth.md

Authentication and identity assertion specification for autonomous agents interacting with ProximaHub APIs.

## Audience
This authentication guide is intended for AI agents, automated schedulers, and background sync services that query ProximaHub biometric and attendance endpoints.

## Protected Resource Metadata
- Resource Identifier: `https://hub.proximalink.pk`
- Protected Resource Metadata: `/.well-known/oauth-protected-resource`
- Authorization Server: `/.well-known/oauth-authorization-server`
- Bearer Methods Supported: `header`
- Scopes Supported: `read`, `write`, `agent`

## Supported Agent Registration & Authentication Methods

### 1. Anonymous Agent Token
Agents without pre-registered identities can request ephemeral access:
- **Registration URI**: `https://hub.proximalink.pk/oauth/anonymous`
- **Identity Types Supported**: `["anonymous"]`
- **Credential Types Supported**: `["bearer_token"]`
- **Claim URI**: `https://hub.proximalink.pk/oauth/anonymous`

### 2. Verified Email Assertion
- **Identity Types Supported**: `["identity_assertion"]`
- **Assertion Types Supported**: `["verified_email"]`
- **Credential Types Supported**: `["bearer_token"]`
- **Claim URI**: `https://hub.proximalink.pk/oauth/claim`

### 3. Identity Assertion (ID-JAG)
- **Identity Types Supported**: `["identity_assertion"]`
- **Assertion Types Supported**: `["urn:ietf:params:oauth:token-type:id-jag"]`
- **Credential Types Supported**: `["bearer_token"]`
- **Revocation URI**: `https://hub.proximalink.pk/oauth/revoke`
- **Events Supported**: `["revocation"]`

## Credential Usage
Include the issued token in all HTTP requests within the `Authorization` header:
```http
Authorization: Bearer <TOKEN>
```