# auth.md

Agent authentication and registration guide for **https://www.efatorh.com**.

## Audience

AI agents and automation clients that need read/write access to the E-Fatorah admin API (`https://www.efatorh.com/api`).

## Discovery documents

- Protected resource metadata: [/.well-known/oauth-protected-resource](/.well-known/oauth-protected-resource)
- Authorization server metadata: [/.well-known/oauth-authorization-server](/.well-known/oauth-authorization-server)
- OpenAPI: [/openapi.json](/openapi.json)

## Registration

Automated public self-registration is not enabled. To provision agent credentials:

1. Email `support@efatorah.com` with your agent name, operator contact, intended scopes, and callback/origin hosts.
2. An operator issues a dedicated admin user (or API user) with least-privilege permissions.
3. Exchange those credentials at the token endpoint below.

## Supported method: password credentials → bearer token

```http
POST /api/auth/login
Content-Type: application/json

{
  "email": "agent@example.com",
  "password": "provisioned-secret",
  "remember": false
}
```

Successful responses include a Sanctum `token`. Send it on API calls:

```http
Authorization: Bearer {token}
```

## Credential use

- Prefer short-lived operational sessions; call `POST /api/auth/logout` when finished.
- Do not embed human passwords in prompts or shared logs.
- Scopes are enforced via Spatie permissions on `/api/admin/*` routes.

## Identity types

| Type | Status |
|------|--------|
| Anonymous bearer via provisioned login | Supported |
| OIDC browser redirect | Not offered for agents |
| ID-JAG / verified email assertions | Not supported yet |