---
title: 5ac.vn — Agent Authentication (auth.md)
description: How an AI agent authenticates to 5ac.vn (G-Company OS). Covers public discovery endpoints (no auth), bearer-token access through the Hermes gateway for protected operations, and the auth.md agent-registration convention.
type: agent-auth-doc
version: 1.20.0
url: https://5ac.vn/auth.md
---

# Agent Authentication — 5ac.vn / G-Company OS

You are an agent. This service exposes two kinds of resources with two different auth
models:

1. **Public discovery assets** — every machine-readable file an agent reads to learn
   about G-Company OS (llms.txt, openapi.json, pricing.md, AGENTS.md, this file, the
   API catalog). These require **no authentication**. Fetch them over HTTPS.
2. **Protected runtime operations** — invoking the G-Company OS agent runtime
   (Hermes Agent). These require a **bearer token** through the Hermes gateway. The
   production 5ac.vn site is static discovery; the runtime is self-hosted per
   deployment, so token issuance is configured by the operator of each deployment.

## Step 1 — Read the discovery surface first

Start here. All of the following are public and need no credentials:

| Resource | URL | What it gives you |
|---|---|---|
| OpenAPI spec | `https://5ac.vn/openapi.json` | Full API contract (OpenAPI 3.1) — versioning, rate limits, errors |
| API catalog | `https://5ac.vn/api-catalog.md` | Human/agent-readable endpoint list (method, auth, description) |
| Agent guide | `https://5ac.vn/agent-docs.md` | What G-Company OS does, when to use it, endpoints, auth |
| LLM index | `https://5ac.vn/llms.txt` | The llms.txt navigation index (product facts + modular sections) |
| Pricing | `https://5ac.vn/pricing.md` | Plan tiers in markdown |
| Operating guide | `https://5ac.vn/AGENTS.md` | Rules for coding agents working on the 5ac site itself |

## Step 2 — Choose an auth method

### Method A — No auth (read-only discovery, default)

Any `GET` on a public discovery asset. This is the only path most agents need. Send
the request over HTTPS and you are done — no token, no signing.

```http
GET https://5ac.vn/openapi.json
Accept: application/json
```

```http
HTTP/1.1 200 OK
Content-Type: application/json
```

### Method B — Bearer token (protected runtime operations)

To call the G-Company OS agent runtime you authenticate to the **Hermes gateway**
with a bearer token configured per deployment. This is the `hermesGateway` security
scheme documented in `openapi.json`.

```
Authorization: Bearer <your-deployment-token>
```

Example (self-hosted deployment, port 4444 by default):

```http
POST https://gateway.example.com/agent/run
Content-Type: application/json
Authorization: Bearer <deployment-token>

{ "agent": "content", "task": "Draft a bilingual blog post" }
```

The token is a per-deployment secret. It is never exposed on the public 5ac.vn site.
Operators mint it when they deploy G-Company OS on their own VPS (see the Hermes
Agent docs: https://hermes-agent.nousresearch.com/docs).

### Method C — auth.md agent registration (OAuth / API-key issuance)

For services built on G-Company OS that want agents to register **on behalf of a
user** without a human filling a signup form, the `auth.md` open protocol applies
(WorkOS spec — the `/sign-up for agents`). The flow is:

**discover → register → (claim if needed) → exchange for an access token → call API → handle revocation**

- **Discover** — `GET /.well-known/oauth-protected-resource` (Protected Resource
  Metadata) and `GET /.well-known/oauth-authorization-server` (authorization-server
  metadata with the `agent_auth` block).
- **Register** — `POST /agent/identity` with one of three identity types:
  `identity_assertion` (an ID-JAG minted by the agent's provider), `service_auth`
  (verified email + claim ceremony), or `anonymous` (no identity yet; claim later).
- **Exchange** — `POST /oauth2/token` with `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer`
  (RFC 7523) to turn the service-signed assertion into an access token, or
  `urn:workos:agent-auth:grant-type:claim` for the claim-ceremony polling grant.
- **Use** — send the access token as `Authorization: Bearer <access_token>`.
- **Revoke** — `POST /oauth2/revoke` (RFC 7009), or react to upstream revocation
  delivered as a Security Event Token (RFC 8935) when the next token exchange
  returns `invalid_grant`.

The current public 5ac.vn site serves the **discovery** layer and documentation. A
production G-Company OS deployment is where the actual `/agent/identity` and
`/oauth2/token` endpoints run; whether they are exposed is an operator decision.

## Step 3 — Errors and retries

- All non-2xx responses on the public discovery surface return **RFC 9457 Problem
  Details** (`application/problem+json`) with a typed `Error` body.
- `429 Too Many Requests` carries `Retry-After`; back off and retry.
- `401 Unauthorized` on a protected endpoint means the bearer token is missing or
  invalid — do not retry the same token; obtain a fresh one.
- 5xx → exponential backoff and retry the same request.

## Contact

- Email: contact@5ac.vn
- Zalo: 0856513513
- Telegram: @Chaos_Magician