# auth.md — Zoho CRM Developer Space Agent Registration

> Specification: https://workos.com/auth-md  
> Repository: https://github.com/workos/auth.md

## Overview

Zoho CRM Developer Space (`https://www.zohocrm.dev`) uses **OAuth 2.0** (via Zoho Accounts) to protect its APIs. AI agents and automated clients should follow the instructions below to register, authenticate, and call protected resources.

---

## Discovery Endpoints

| Resource | URL |
|---|---|
| OpenID Connect Configuration | `https://www.zohocrm.dev/.well-known/openid-configuration` |
| OAuth Authorization Server | `https://www.zohocrm.dev/.well-known/oauth-authorization-server` |
| Protected Resource Metadata | `https://www.zohocrm.dev/.well-known/oauth-protected-resource` |
| API Catalog | `https://www.zohocrm.dev/.well-known/api-catalog` |

---

## Agent Registration

To obtain credentials for automated access:

1. Visit the [Zoho API Console](https://api-console.zoho.com/) and create a **Server-based Application** or **Self Client** for programmatic/agent access.
2. Select the required OAuth scopes (see below).
3. Note your `client_id` and `client_secret`.

**Register URI:** `https://api-console.zoho.com/`

**Supported Identity Types:**
- `oauth2_client` — standard OAuth 2.0 client credentials
- `service_account` — long-lived service accounts for agent use

**Credential Types:**
- `client_secret` — client ID + secret pair
- `pkce` — Proof Key for Code Exchange (for public clients)

---

## OAuth Endpoints

| Endpoint | URL |
|---|---|
| Authorization | `https://accounts.zoho.com/oauth/v2/auth` |
| Token | `https://accounts.zoho.com/oauth/v2/token` |
| Revocation | `https://accounts.zoho.com/oauth/v2/revoke` |
| JWKS | `https://accounts.zoho.com/oauth/v2/certs` |
| UserInfo | `https://accounts.zoho.com/oauth/v2/userinfo` |

---

## Supported Scopes

| Scope | Description |
|---|---|
| `ZohoCRM.modules.ALL` | Full access to all CRM modules |
| `ZohoCRM.modules.READ` | Read-only access to CRM modules |
| `ZohoCRM.settings.ALL` | Full access to CRM settings |
| `ZohoCRM.settings.READ` | Read-only access to CRM settings |
| `ZohoCRM.users.ALL` | Full access to CRM users |
| `ZohoCRM.org.ALL` | Full access to CRM organization data |

---

## Grant Types

- `authorization_code` — standard 3-legged OAuth flow
- `refresh_token` — refresh expired access tokens
- `client_credentials` — machine-to-machine / agent access

---

## Recommended Agent Flow

```
1. POST https://accounts.zoho.com/oauth/v2/token
   grant_type=client_credentials
   client_id=<your_client_id>
   client_secret=<your_client_secret>
   scope=ZohoCRM.modules.READ

2. Use the returned access_token as a Bearer token:
   Authorization: Bearer <access_token>

3. Call APIs documented at:
   https://www.zohocrm.dev/explore/client-script/webapi
```

---

## API Documentation

- **Web API Reference:** `https://www.zohocrm.dev/explore/client-script/webapi`
- **Client API Reference:** `https://www.zohocrm.dev/explore/client-script/clientapi`
- **Widget SDK:** `https://www.zohocrm.dev/explore/widgets`
- **OpenAPI Spec:** `https://www.zohocrm.dev/openapi.json`

---

## Revocation

To revoke a token:

```
POST https://accounts.zoho.com/oauth/v2/revoke
token=<access_token_or_refresh_token>
```