# url2image auth.md

Nothing here needs a user account. An agent only needs a stable identity so its
credits and its batches survive a restart. There are three ways to get one.

## Agent registration

This service accepts agent registration. There is no human sign up step and no
user consent ceremony to complete: an agent registers itself and starts working.

| Field | Value |
| --- | --- |
| `register_uri` | `https://url2image.com/oauth/register` |
| `identity_types_supported` | `anonymous` |
| `credential_types_supported` | `oauth_client_credentials`, `api_key` |
| `claim_uri` | `https://url2image.com/oauth/token` |
| `grant_types_supported` | `client_credentials` |
| `scopes_supported` | `screenshots:write`, `screenshots:read`, `credits:purchase` |

Registration is anonymous. An agent registers without asserting a user identity,
receives client credentials immediately, and holds the account itself. There is
no ID-JAG or verified email flow here because there is no user to bind to.

Discovery for all of this is machine readable:

- Authorization server metadata, including the `agent_auth` block:
  `https://url2image.com/.well-known/oauth-authorization-server`
- Protected resource metadata:
  `https://url2image.com/.well-known/oauth-protected-resource`

To revoke, stop using the credential and register again. Credentials are bearer
secrets with no server side session, so there is nothing to log out of. An API
key or client secret cannot be listed or recovered after it is issued.

The three ways to register are below.

## 1. API key, one call

```
POST https://url2image.com/api/v1/keys
```

Returns `{"key": "u2i_..."}`. Send it as `Authorization: Bearer u2i_...` or
`X-API-Key: u2i_...` on every request. Store it: it is the only handle on that
account and it cannot be listed or recovered.

## 2. Anonymous OAuth client credentials

1. `POST https://url2image.com/oauth/register` returns a client id and secret.
2. `POST https://url2image.com/oauth/token` with `grant_type=client_credentials`,
   `client_id` and `client_secret` returns a bearer token valid for 24 hours.
3. Send `Authorization: Bearer TOKEN` on API and MCP requests.

Scopes are `screenshots:write`, `screenshots:read` and `credits:purchase`.

## 3. Nothing at all

Browsers get a signed cookie automatically. Requests with no credential get a
fresh anonymous account, which is fine for a one off render and useless for
anything that needs to come back later.

## Paying

Card details are never accepted by this API. Credit purchases go through
Stripe's hosted checkout page, and an agent should hand the URL to a person
rather than trying to complete it. Agents holding a wallet can pay per call over
x402 instead: https://url2image.com/.well-known/x402.

Support: support@builtwith.com