# Sno.ai auth.md: sign up or sign in for a person

You do not need a browser. The person signs up or signs in using the existing Sno.ai forms, then confirms your connection with a link and a 6-digit code.

## Network access

In a sandbox, allow network access to www.sno.ai and sno.ai with both GET and POST methods.

## Discover

Fetch https://www.sno.ai/.well-known/oauth-protected-resource and https://www.sno.ai/.well-known/oauth-authorization-server. Use their endpoint URLs. This guide is hosted at https://www.sno.ai/auth.md.

## Register with the person's email

POST JSON to https://www.sno.ai/api/v1/agent-auth/identity:

```json
{"type":"service_auth","login_hint":"person@example.com"}
```

Keep the returned `claim_token`. Show the person `claim.verification_uri` and `claim.user_code`. The person visits the link, signs up if new or signs in if existing, and types that code. Never prefill it or confirm for the person. The code lasts 30 minutes.

## Poll for the credential

POST a form with `Content-Type: application/x-www-form-urlencoded` to https://www.sno.ai/api/v1/agent-auth/token:

```text
grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=<claim_token>
```

Poll every 5 seconds while the response is `authorization_pending`. After confirmation, the response contains `access_token`, `identity_assertion`, `assertion_expires`, `token_type: "Bearer"`, `expires_in` and `scope: "sno.account"`.

## Use and reuse your credential

Send `Authorization: Bearer <access_token>` to Sno.ai. This is an ordinary account session with the person's full account permissions. It lasts 30 days and renews with use. Save both the access token and identity assertion in your own secret store and reuse them. Do not register again for each task: every new registration asks the person to confirm again.

If the session expires, POST a form to the same token endpoint:

```text
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<identity_assertion>
```

The claimed identity assertion lasts 90 days from confirmation. It can be exchanged even after the original registration's 24-hour unclaimed window passes. The person can revoke the registration from account settings at any time.

## Anonymous event intake before confirmation

POST JSON `{"type":"anonymous"}` to the identity endpoint. Save its `identity_assertion` and `claim_token`. Exchange the assertion using the JWT bearer grant above to get a pre-claim access token. An unclaimed registration lasts 24 hours. To connect it to a person, POST JSON `{"claim_token":"<claim_token>","email":"person@example.com"}` to https://www.sno.ai/api/v1/agent-auth/claim, then show the returned `claim` link and code and poll as above. A service-auth registration can also start a new ceremony here; its email must match the original login hint and may be omitted.

| Scope | Access |
| --- | --- |
| sno.events | Only POST /api/v1/events, /api/v1/otlp/v1/logs and /api/v1/otlp/v1/metrics; events are held without an account and include the user-not-found warning. |
| sno.account | All HTTP endpoints the person's ordinary session can access. Server actions are not HTTP endpoints for agents. |

Pre-claim access tokens stop working once the person confirms. A confirmed account session is also accepted at the event intakes; its events remain held without machine attribution. These intakes do not grant access to account data before confirmation.

## What you can read after sign-in

- GET https://www.sno.ai/api/v1/account/summary returns `{version:1,generated_at,sections,errors}`. Ignore unknown section names and fields. Each section may change independently; a failed section is omitted and its reason appears in `errors` without failing the rest. Initial sections: account, plan_and_usage, computers, agents.
- GET https://www.sno.ai/api/v1/account/computers
- GET https://www.sno.ai/api/v1/activity
- GET https://www.sno.ai/api/v1/usage/bar
- GET https://www.sno.ai/api/v1/consent
- GET https://www.sno.ai/api/v1/audit/verify
- BetterAuth's https://www.sno.ai/api/auth/ endpoints include sessions, organization and API key operations.

The account session also permits POST /api/v1/consent and DELETE /api/v1/user/data when the person requests those operations. Usage reports contain percentages, reset times and purchased balance, not raw units, points or token counts.

## Revoke

POST a form `token=<access_token>&token_type_hint=access_token` to https://www.sno.ai/api/v1/agent-auth/revoke. It returns 200 even if the token is already gone. This revokes that access token; the assertion still works. Revoking the registration from account settings ends all its sessions and prevents future assertion exchanges.

## Errors

| Status and error | Next action |
| --- | --- |
| 400 authorization_pending | Wait 5 seconds and poll again. |
| 400 expired_token | Request a fresh claim ceremony before the registration's 24-hour window ends; after that, register again. |
| 400 wrong_code | Ask the person to enter the displayed code. |
| 403 email_mismatch | The person must sign in using the registered email. |
| 400 invalid_grant | The credential expired, is invalid or its registration was revoked. |
| 400 invalid_request | Correct the JSON or form fields. |
| 400 unsupported_identity_type | Use anonymous or service_auth; identity_assertion registration is not supported. |
| 400 unsupported_grant_type | Use one of the two grant types documented above. |
| 401 unauthorized | A valid account session is required. Read the WWW-Authenticate metadata link to discover this flow. |
| 424 temporarily_unavailable | The operation failed temporarily; retry later. |