> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grantex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete REST API reference for the Grantex Auth Service

The Grantex Auth Service exposes a REST API covering agent registration, authorization flows, token management, audit logging, policy enforcement, anomaly detection, compliance exports, SCIM provisioning, SSO, billing, FIDO2/WebAuthn passkey management, W3C Verifiable Credentials, and DID infrastructure.

## Base URLs

| Environment    | URL                       |
| -------------- | ------------------------- |
| **Production** | `https://api.grantex.dev` |
| **Local**      | `http://localhost:3001`   |

## Authentication

Most endpoints require a **Bearer token** in the `Authorization` header. This is your developer API key, obtained via `POST /v1/signup`.

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.grantex.dev/v1/agents
```

SCIM 2.0 user endpoints use a separate **SCIM Bearer token**, created via `POST /v1/scim/tokens`.

Public endpoints (health, JWKS, consent UI, SSO flow) require no authentication.

## Rate Limits

<Note>
  These are current repository defaults. Source implementation does not by itself confirm that a managed environment has been deployed with the same configuration.
</Note>

| Endpoint                                               | Limit                               |
| ------------------------------------------------------ | ----------------------------------- |
| Default Fastify IP policy (routes without an override) | 5,000 requests/minute per source IP |
| Standard developer API-key - Free plan                 | 100 requests/minute per developer   |
| Standard developer API-key - Pro plan                  | 500 requests/minute per developer   |
| Standard developer API-key - Enterprise plan           | 2,000 requests/minute per developer |
| `POST /v1/authorize`                                   | 10 requests/minute per developer    |
| `POST /v1/token`                                       | 20 requests/minute                  |
| `POST /v1/token/refresh`                               | 20 requests/minute                  |
| `GET /.well-known/jwks.json`                           | Not rate-limited                    |

A route-specific Fastify limit replaces the 5,000 requests/minute default for that route. The Redis-backed standard developer API-key plan budget is an additional policy whenever standard API-key authentication applies.

Commerce, the SCIM Bearer data-plane routes under `/scim/v2/*`, admin, and other custom-auth routes do not consume the standard developer API-key plan bucket; their active Fastify policy still applies. The standard API-key-authenticated `/v1/scim/tokens` management routes do consume the plan bucket.

## OpenAPI Spec

The full OpenAPI 3.1 specification is available at [`openapi.yaml`](https://github.com/mishrasanjeev/grantex/blob/main/docs/openapi.yaml). You can import it into Swagger Editor, Postman, or any OpenAPI-compatible tool.