# EasyData auth.md

EasyData lets agents act for a user only after that user verifies their email and approves the connection.

## Discover

- Protected REST resource: https://easydata.cc/.well-known/oauth-protected-resource/api/public/v1
- Protected MCP resource: https://easydata.cc/.well-known/oauth-protected-resource/api/mcp
- Authorization server: https://easydata.cc/.well-known/oauth-authorization-server
- MCP endpoint: https://easydata.cc/api/mcp

## Standard OAuth for MCP and browser-capable agents

1. POST public client metadata to https://easydata.cc/api/oauth/register. Use token_endpoint_auth_method=none.
2. Start Authorization Code flow at https://easydata.cc/oauth/authorize with response_type=code, an exact registered redirect_uri, state, scope (read or read write), resource, and PKCE S256 challenge.
3. The user signs in or creates an EasyData account through verified-email magic link and approves the requested access.
4. Exchange the one-time code at https://easydata.cc/api/oauth/token. Access tokens last one hour. Refresh tokens last 30 days and rotate on every use.

## Agent-native verified-email claim

1. Register a public client as above and include urn:workos:agent-auth:grant-type:claim in grant_types.
2. POST JSON to https://easydata.cc/api/agent/identity using either supported verified-email form:
   - service_auth: type=service_auth with client_id, login_hint, resource, and scope.
   - identity_assertion: type=identity_assertion, assertion_type=verified_email, assertion set to the user's email, plus client_id, resource, and scope.
3. Show the returned claim.verification_uri and claim.user_code to the user. The code must be entered on EasyData, never sent back to the agent in chat.
4. Poll https://easydata.cc/api/oauth/token no faster than claim.interval using form fields grant_type=urn:workos:agent-auth:grant-type:claim, client_id, claim_token, and resource.
5. authorization_pending means the user has not approved yet. slow_down means polling was too fast. After approval the response contains access_token and rotating refresh_token.

If the ten-minute user-code attempt expires, POST the original claim_token to https://easydata.cc/api/agent/identity/claim to receive a fresh verification URI and code. The overall registration expires after 24 hours.

## Credentials and revocation

Send access tokens only in Authorization: Bearer headers. Never expose them in URLs or browser bundles. Refresh with grant_type=refresh_token, client_id, refresh_token, and resource. Reusing an already-rotated refresh token revokes the connection. Revoke at https://easydata.cc/api/oauth/revoke or from EasyData Settings → Connected Agents.

## API use

Prefer MCP. REST agents may call https://easydata.cc/api/public/v1/named so payloads use schema field names. One-time credit packages are available through https://easydata.cc/api/public/v1/credit-products and https://easydata.cc/api/public/v1/credit-purchases. Read https://easydata.cc/.well-known/agent-skills/easydata-data/SKILL.md before creating schemas, records, or credit checkouts.