# auth.md

You are an agent. TeamIN supports **agent registration discovery**: discover → register or claim with a human → exchange credentials → call the API.

This file is the TeamIN `auth.md` skill. Prefer the machine-readable documents when they disagree with prose.

## Audience

Agents acting for a **human company admin or employee** who already has (or is creating) a TeamIN tenant. Do not register anonymous HR tenants for scraping payroll or employee data.

## Step 1 — Discover

Fetch protected resource metadata:

```http
GET https://teamin-hr.com/.well-known/oauth-protected-resource
```

Then authorization server metadata:

```http
GET https://teamin-hr.com/.well-known/oauth-authorization-server
```

Issuer in both documents is `https://teamin-hr.com`. Token and registration endpoints live on the API host `https://api-roi-v2.hostly-eg.com`.

## Step 2 — Register

`agent_auth.register_uri`:

```http
POST https://api-roi-v2.hostly-eg.com/api/auth/register
Content-Type: application/json
```

Supported identity types (from `agent_auth.identity_types_supported`):

- `anonymous` — only with an explicit human request to create a tenant; credentials are `access_token`.
- `identity_assertion` with `verified_email` — walk the user to `claim_uri` `https://teamin-hr.com/login` (or the waiting list at `https://teamin-hr.com/#contact`).

Do not probe extra `POST /agent/auth` routes. Registration can create accounts.

## Step 3 — Claim (verified email)

If the user already has an account, send them to:

https://teamin-hr.com/login

Password reset: https://teamin-hr.com/ForgetPassword

## Step 4 — Exchange for an access token

Grant types: `password`, `refresh_token`.

```http
POST https://api-roi-v2.hostly-eg.com/api/auth/login
Content-Type: application/json

{"email":"<verified user email>","password":"<user password>"}
```

Send the token as `Authorization: Bearer <token>` (`bearer_methods_supported`: `header`).

Refresh: `POST https://api-roi-v2.hostly-eg.com/api/auth/refresh`

Revoke / logout: `POST https://api-roi-v2.hostly-eg.com/api/auth/logout`

## Step 5 — Call APIs

See https://teamin-hr.com/docs/api and https://teamin-hr.com/docs/openapi.json

Scopes advertised: `profile`, `hr.read`, `hr.write`, `hr.admin`. Apply least privilege. Never log tokens.

## JWKS / Web Bot Auth

Public keys: https://teamin-hr.com/.well-known/jwks.json

HTTP Message Signatures directory: https://teamin-hr.com/.well-known/http-message-signatures-directory