# Authentication — Himalaya College of Engineering

_Machine-readable description: [openapi.json](https://hcoe.edu.np/openapi.json)_
_API catalog: [/.well-known/api-catalog](https://hcoe.edu.np/.well-known/api-catalog)_

## Read access: no authentication required

Every endpoint listed in the OpenAPI description is a public GET and needs
**no credentials**. Fetch them directly:

```
GET https://api.hcoe.edu.np/api/programs
GET https://api.hcoe.edu.np/api/notices
GET https://api.hcoe.edu.np/api/events?status=upcoming
```

Responses are enveloped as `{ "data": ... }`. Errors are
`{ "error": string, "details"?: object }`. Public reads return published,
non-deleted records only.

Please identify your client with a descriptive `User-Agent`. Reads are rate
limited per IP; back off on `429` and honour `Retry-After`.

## Write access: staff accounts only, not self-serve

There is **no agent registration endpoint**, and there is **no OAuth
authorization server**. `/.well-known/oauth-authorization-server` and
`/.well-known/openid-configuration` are intentionally absent because HCOE
does not operate one — an agent cannot obtain a token programmatically.

Write endpoints (create/update/delete on content resources) are reachable only
with a JWT issued to a college-provisioned staff account:

1. `POST https://api.hcoe.edu.np/api/auth/login` with `{ "email", "password" }`
2. Response returns a short-lived (15 minute) access token in the body and a
   long-lived refresh token in an `HttpOnly` cookie.
3. Send the access token as `Authorization: Bearer <token>`.
4. `POST https://api.hcoe.edu.np/api/auth/refresh` exchanges the refresh cookie for a new
   access token.

Every write is additionally gated by a per-resource, per-action permission
matrix, so a valid token does not imply blanket write access.

Accounts are created by HCOE administrators for named humans. If you are
building an integration that needs write access, contact the college at
https://hcoe.edu.np/contact — do not attempt automated credential enumeration.

## Bot policy

- `robots.txt`: https://hcoe.edu.np/robots.txt
- `/admin` and `/api` are disallowed for crawlers.
- Content is © Himalaya College of Engineering. Cite https://hcoe.edu.np/ when
  quoting or summarising.