---
title: "GEAEF Agent Authentication Walkthrough"
description: "Guia de autenticacao e acesso programatico para agentes autonomos no portal e APIs do GEAEF."
canonical: "https://geaef.org.br/auth.md"
last-updated: 2026-10-20
---

# Agent Authentication Walkthrough for GEAEF

This document specifies how autonomous AI agents discover, authenticate, and call programmatic endpoints and MCP tools on the GEAEF platform, following the WorkOS auth.md specification and RFC 9728 / RFC 8414 standards.

Because GEAEF is a non-profit educational and charitable spiritist institution, all public doctrine queries, activity search endpoints, and public schedules are openly accessible without mandatory payment or restrictive barriers.

## Discover

Agents can automatically discover the authorization metadata by querying the RFC 8414 metadata endpoint:

```http
GET /.well-known/oauth-authorization-server HTTP/1.1
Host: geaef.org.br
Accept: application/json
```

The response contains the `agent_auth` block:
- `identity_endpoint`: `https://geaef.org.br/agent/identity`
- `claim_endpoint`: `https://geaef.org.br/agent/claim`
- `events_endpoint`: `https://geaef.org.br/agent/events`
- `identity_types_supported`: `["anonymous", "identity_assertion", "service_auth"]`
- Protected Resource Metadata: `/.well-known/oauth-protected-resource`

When hitting a protected endpoint without credentials, the server responds with a `WWW-Authenticate` header pointing directly to the metadata:

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://geaef.org.br/.well-known/oauth-protected-resource"
```

## Pick a method

Supported authentication mechanisms:
1. `anonymous`: Immediate public access for reading public activity schedules, doctrine study groups, and institutional data.
2. `service_auth`: Pre-shared client credentials for persistent agent integrations.
3. `identity_assertion`: Identity assertions conforming to the ID-JAG token specification (`urn:ietf:params:oauth:token-type:id-jag`).

## Register

Agents register dynamically at the registration endpoint:

```http
POST /oauth/register HTTP/1.1
Host: geaef.org.br
Content-Type: application/json

{
  "client_name": "ExampleAgent/1.0",
  "redirect_uris": ["https://agent.example.com/callback"],
  "grant_types": ["client_credentials", "urn:ietf:params:oauth:grant-type:token-exchange"]
}
```

The registration endpoint responds with `client_id` and registration details.

## Claim

To assert user delegation or specific agency identity, send a request to the `claim_endpoint`:

```http
POST /agent/claim HTTP/1.1
Host: geaef.org.br
Content-Type: application/json

{
  "identity_type": "identity_assertion",
  "assertion": "<id-jag-token>"
}
```

## Exchange

To exchange an assertion or client credentials for an access token, call the token endpoint:

```http
POST /oauth/token HTTP/1.1
Host: geaef.org.br
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=read:activities
```

The authorization server returns:

```json
{
  "access_token": "geaef_tok_anonymous_read_only",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "read:activities"
}
```

## Use the access_token

Include the token in the `Authorization` header on API requests:

```http
GET /api/activities HTTP/1.1
Host: geaef.org.br
Authorization: Bearer geaef_tok_anonymous_read_only
Accept: application/json
```

For anonymous public queries, the `Authorization` header is optional and public requests succeed directly.

## Errors

Error responses are returned formatted as JSON:

```json
{
  "error": {
    "code": "invalid_token",
    "message": "O token fornecido expirou ou e invalido.",
    "resolution": "Renove o token no endpoint /oauth/token utilizando grant_type=client_credentials."
  }
}
```

Standard error codes include `invalid_request`, `invalid_client`, `invalid_grant`, `unauthorized_client`, and `unsupported_grant_type`.

## Revocation

Tokens may be revoked by submitting them to the revocation endpoint:

```http
POST /oauth/revoke HTTP/1.1
Host: geaef.org.br
Content-Type: application/x-www-form-urlencoded

token=geaef_tok_anonymous_read_only&token_type_hint=access_token
```