# Agent Authentication & Registration Guide

> Instructions for autonomous AI agents to discover authentication options, register, acquire credentials, and interact with the RovaSpace API.

## Overview

RovaSpace supports OAuth 2.0 and OpenID Connect (OIDC) authentication flows tailored for autonomous agents, service accounts, and user-delegated sessions.

## 1. Discovery Endpoints

Agents can programmatically discover server capabilities and authentication parameters via the following metadata endpoints:

- **OAuth Authorization Server Metadata**: `/.well-known/oauth-authorization-server`
- **OAuth Protected Resource Metadata**: `/.well-known/oauth-protected-resource`
- **OpenID Connect Discovery**: `/.well-known/openid-configuration`
- **API Catalog**: `/.well-known/api-catalog`

## 2. Agent Registration

Agents can register dynamically or obtain API credentials through the registration endpoint.

- **Registration Endpoint**: `/api/auth/register`
- **Supported Identity Types**: `agent`, `user_delegated`, `service_account`
- **Supported Credential Types**: `client_credentials`, `bearer_token`, `authorization_code`

### Registration Request Example

```http
POST /api/auth/register HTTP/1.1
Host: www.rovaspace.com
Content-Type: application/json

{
  "client_name": "MyAutonomousAgent",
  "grant_types": ["client_credentials", "authorization_code"],
  "response_types": ["code", "token"],
  "scope": "openid profile email"
}
```

## 3. Obtaining Access Tokens

### Client Credentials Flow (Machine-to-Machine)

```http
POST /api/auth/token HTTP/1.1
Host: www.rovaspace.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&scope=openid+profile+email
```

### Authorization Code Flow (User-Delegated)

1. Direct the user to the authorization endpoint:
   `GET /api/auth/signin?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=openid+profile`
2. Exchange code for access token at `/api/auth/token`.

## 4. Making Authenticated Requests

Include the access token in the `Authorization` HTTP header:

```http
GET /api/trpc/workspace.getWorkspaces HTTP/1.1
Host: www.rovaspace.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
```

## 5. Token Revocation

To invalidate an active token:

```http
POST /api/auth/revoke HTTP/1.1
Host: www.rovaspace.com
Content-Type: application/x-www-form-urlencoded

token=YOUR_ACCESS_TOKEN
```

## Supported Scopes

- `openid`: Standard OpenID Connect subject identification.
- `profile`: Access agent/user profile details.
- `email`: Access registered email address.