# ArenAPI agent authentication

You are an agent. ArenAPI supports user-claimed registration through the WorkOS auth.md protocol. Discover the service, register with the account owner's email, ask the owner to confirm the request, exchange the claim for an access token, then connect to the Model Context Protocol server.

## 1. Discover

Fetch `https://arenapi.com/.well-known/oauth-protected-resource/mcp`, then fetch the first authorization server's `/.well-known/oauth-authorization-server` document. Structured metadata is authoritative. Use the protected resource `resource` value when exchanging credentials.

## 2. Register with the account owner's email

Before transmitting an email address, explain that ArenAPI is the service and that the resulting credential can configure providers, operate sandboxes, manage application programming interface keys, and manage billing. After the owner consents, send:

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

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

Keep the returned `claim_token` only until the ceremony finishes. Show `claim.user_code` and `claim.verification_uri` to the owner in one message. Tell the owner to open the ArenAPI page, follow the email confirmation link, and enter the code there. Never ask the owner to send the code back to you.

## 3. Poll for confirmation

Poll `https://arenapi.com/oauth2/token` no faster than `claim.interval` seconds:

```http
POST https://arenapi.com/oauth2/token
Content-Type: application/x-www-form-urlencoded

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

`authorization_pending` means the owner has not finished. On `slow_down`, add at least five seconds to the polling interval. If the code window expires while the registration remains active, request a fresh code:

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

{"claim_token":"<claim_token>","email":"owner@example.com"}
```

A successful poll returns a bearer access token and a service-signed `identity_assertion`.

## 4. Connect and operate sandboxes

Send `Authorization: Bearer <access_token>` to `https://arenapi.com/mcp` or `https://arenapi.com/api/v1`. For the Model Context Protocol server, initialize the connection and call `tools/list` before choosing a tool. Every business operation in the versioned application programming interface has a corresponding tool.

Do not create or destroy sandboxes, execute commands, write files, reveal a newly created key, remove providers, or begin billing unless the owner explicitly asks.

## 5. Renew or revoke

Exchange an unexpired assertion at `https://arenapi.com/oauth2/token`:

```http
POST https://arenapi.com/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<identity_assertion>&resource=https://arenapi.com/mcp
```

To revoke an access token, post `token=<access_token>&token_type_hint=access_token` to `https://arenapi.com/oauth2/revoke`.

## Scopes

- `providers:read` and `providers:write`: inspect and configure sandbox providers.
- `sandboxes:read` and `sandboxes:write`: inspect and operate sandboxes and their files.
- `api_keys:read` and `api_keys:write`: inspect, create, and revoke application programming interface keys.
- `billing:read` and `billing:write`: inspect a subscription and start Stripe-hosted billing sessions.

Documentation: https://arenapi.com/docs
Pricing: https://arenapi.com/#pricing
Terms: https://arenapi.com/terms
Privacy: https://arenapi.com/privacy
Integration help: support@arenapi.com