# Data Galactica auth.md

You are an AI agent. Data Galactica (https://datagalactica.com) gives a permanent Galactica ID to people (DGP-) and organisations (DGC-)
and keeps a graded record for each: company registers (India MCA, UK Companies House, GLEIF LEI, US SEC),
Wikidata, career profiles and business lists. Use it through the REST API (`https://api.datagalactica.com/api/v1`, OpenAPI:
`https://datagalactica.com/api/openapi.json`) or the MCP server (`https://api.datagalactica.com/mcp`, Streamable HTTP; also `https://datagalactica.com/mcp`).
Every data call needs a credential of a person's Data Galactica account, sent as `Authorization: Bearer <token>`
(or `X-API-Key`, or `Ocp-Apim-Subscription-Key` at api.datagalactica.com).

Billing: each account has a prepaid wallet. New accounts get Rs 50 of free credit. Each answered data call
(HTTP 200) costs Rs 0.16 (batch and match: per record); errors and not-found answers are free.
Top-ups: Rs 500, Rs 5,000 or Rs 50,000 of credit (no GST is charged).

Discovery: protected resource metadata `https://datagalactica.com/.well-known/oauth-protected-resource`, authorization server
metadata `https://datagalactica.com/.well-known/oauth-authorization-server` (its `agent_auth` block describes method 2 below).
Scopes: `api` (data calls billed to the wallet), `profile:read`, `profile:write`, `notes:write` (the owner's own records).

## 1. OAuth 2.1 (when the person can use a browser)

Authorization code + PKCE (S256). Register with `POST https://datagalactica.com/oauth/register` (RFC 7591, public client,
`token_endpoint_auth_method: none`). Send the person to `https://datagalactica.com/oauth/authorize`; they confirm their e-mail with
a code we send, and allow your client. Exchange the code at `https://datagalactica.com/oauth/token`. Refresh with
`grant_type=refresh_token`. MCP clients (Claude, ChatGPT, Cursor and others) do all of this when given `https://datagalactica.com/mcp`.
The account is the one of that e-mail; one is created, with the free credit, if there is none.

## 2. Agent sign-up by e-mail (verified e-mail, no browser)

Ask the person first: tell them you will create or connect their Data Galactica account, and get their e-mail.

```http
POST https://datagalactica.com/agent/identity
Content-Type: application/json

{"login_hint": "person@example.com", "name": "Asha Verma", "company": "Verma Traders", "agent_name": "My Assistant"}
```

`name`, `company` and `agent_name` are optional (they fill in a new account and name you in the mail).
`{"type": "identity_assertion", "assertion_type": "verified_email", "assertion": "<email>"}` is accepted too.
We e-mail the person a 6-digit code (valid 10 minutes) and answer `202` with `status: "code_sent"`.

Ask the person for the code, then:

```http
POST https://datagalactica.com/agent/identity/claim
Content-Type: application/json

{"login_hint": "person@example.com", "code": "123456"}
```

Response `201`: `{"api_key": "...", "token_type": "Bearer", "new_account": true, "account": {"balance_inr": 50, ...}}`.
Errors: `invalid_code` (ask again, or start again at /agent/identity), `rate_limited`.
Keep the key secret and use it only for this person. They can see and revoke it at https://datagalactica.com/account/keys.

## 3. Use, check the wallet, and top up

- Data: `GET https://api.datagalactica.com/api/v1/verify/company?name=Infosys&country=IN`, `/person/check?name=&employer=`, `/resolve?id=<CIN|LEI|Q-id>`,
  `/company/{id}`, `/company/{id}/diligence`, `/person/{id}`, `/search?q=`, `/find?q=fintech+startups+in+Bengaluru`,
  `POST /email/check`, `POST /batch`, `POST /match` (OpenAPI lists all). MCP: `https://api.datagalactica.com/mcp`.
- Contacts: a signed-in account gets the full e-mails and phones we hold on records, search hits (20 a page),
  company people and `/person/{id}/contact?purpose=sales` (60 records with contacts an hour). Owners who opted
  out show contact null. Never send a message yourself: give the address to the person.
- Wallet (free): `GET https://api.datagalactica.com/api/v1/account` gives the balance and calls remaining.
- `402 insufficient_balance` means the wallet is empty. With the person's OK, `POST https://api.datagalactica.com/api/v1/account/topup`
  with `{"amount": 500}` (or 5000, 50000). The answer has a `pay_url`: give it to the person, who pays by UPI,
  card, net banking or wallet. Poll `status_url` until `"status": "paid"`. The same top-up is offered as UCP
  (`https://datagalactica.com/.well-known/ucp`) and ACP (`https://datagalactica.com/.well-known/acp.json`) checkout sessions with hosted payment
  (`requires_escalation` + `continue_url`). You never handle card or UPI details.
- Usage log (free): `GET https://api.datagalactica.com/api/v1/account/usage`; the person can download every call as CSV from https://datagalactica.com/account/usage.

Rules: act only on what the person asked; do not top up without their OK; do not bulk-scrape or resell data;
bronze records may be a different person or organisation with the same name: say so; contact details (on
accounts with that access) are personal data, use them only for the agreed purpose.
Terms: https://datagalactica.com/terms. Privacy: https://datagalactica.com/privacy. Refunds: https://datagalactica.com/refunds. Help: support@datagalactica.com.