# DataPasa auth.md

This document explains how an automated client (an AI agent, a script, a CI job) gets access to the DataPasa API at `https://cloud.datapasa.com/api`. DataPasa does not run an OAuth 2.0 authorization server and does not issue API keys. Access is based on a customer account and short lived bearer tokens.

## Audience

Agents acting on behalf of a DataPasa customer who wants to read pricing, create an account, top up a balance or manage servers. Public pricing data needs no credentials at all.

## Public access, no credentials

These endpoints are open and cached for five minutes:

- `GET https://cloud.datapasa.com/api/public/catalog`: VPS locations, plans, prices in USD and referral program terms.
- `GET https://cloud.datapasa.com/api/public/games`: game server catalog with plans and prices.

The machine readable description of the whole API is at `https://datapasa.com/openapi.json`. A human readable guide is at `https://datapasa.com/docs/api.md`.

## Registration

An account belongs to a person or a legal entity. One account per customer. The customer must be at least 18 years old and must accept the Terms of Service, the Privacy Policy and the Acceptable Use Policy.

- In a browser: `https://cloud.datapasa.com/register`
- By API: `POST https://cloud.datapasa.com/api/auth/register`

```json
{
  "firstname": "Ada",
  "lastname": "Lovelace",
  "email": "ada@example.com",
  "password": "at least 8 characters",
  "acceptedTerms": true
}
```

The response is `201` with an access token and a refresh token. A verification email is sent immediately. Ordering servers requires a verified email address, so the customer has to open the link from that email. Registration is limited to 10 attempts per hour per IP address.

Policies: `https://datapasa.com/en/terms`, `https://datapasa.com/en/privacy-policy`, `https://datapasa.com/en/acceptable-use`, `https://datapasa.com/en/refund-policy`.

## Credentials

- `POST https://cloud.datapasa.com/api/auth/login` with `{"email": "...", "password": "..."}` returns `{"accessToken": "...", "expiresIn": 900, "refreshToken": "..."}`.
- The access token is a JWT valid for 15 minutes.
- The refresh token is valid for 30 days. `POST /api/auth/refresh` with `{"refreshToken": "..."}` returns a new pair and invalidates the old refresh token.
- `POST /api/auth/logout` with `{"refreshToken": "..."}` revokes it.
- Login is limited to 10 attempts per 15 minutes per email and IP address.

Passkeys (WebAuthn) are supported for browser sign in but are not usable from a headless client.

## Using credentials

Send the access token in the `Authorization` header:

```
Authorization: Bearer <accessToken>
```

A missing or expired token gives `401`. Refresh the token and retry.

Authenticated endpoints other than `/api/me` are protected by a device check. Until the customer completes it in the control panel at `https://cloud.datapasa.com`, those endpoints answer `403` with `{"code": "FINGERPRINT_REQUIRED"}`. `GET /api/me` reports `fingerprintRequired` so a client can detect this state and hand over to the customer.

## Not supported

- OAuth 2.0 authorization code, client credentials or device flows
- OpenID Connect
- API keys, personal access tokens or service accounts
- Anonymous agent registration, identity assertions or claim ceremonies

If you need one of these for an integration, write to `support@datapasa.com`.

## Discovery

- Protected resource metadata: `https://datapasa.com/.well-known/oauth-protected-resource`
- API catalog (RFC 9727): `https://datapasa.com/.well-known/api-catalog`
- OpenAPI: `https://datapasa.com/openapi.json`
- Site overview for agents: `https://datapasa.com/llms.txt`

## Contact

`support@datapasa.com` for account and API questions, `abuse@datapasa.com` for abuse reports.