# Panoptic Scans auth.md

Panoptic Scans is a vulnerability scanning service. This document tells agents how an account holder grants access to the API at https://panopticscans.com/api and the MCP server at https://panopticscans.com/mcp.

Agents act for an account that a person already controls. This service does not accept ID-JAG assertions (`urn:ietf:params:oauth:token-type:id-jag`) and it does not offer anonymous registration.

## Audience

Autonomous agents calling the Panoptic Scans API or MCP server on behalf of an account holder.

## MCP clients

Clients that speak OAuth, including Cursor, sign in through the browser. They register at https://panopticscans.com/oauth/register, send the account holder to https://panopticscans.com/oauth/authorize, and exchange the authorization code at https://panopticscans.com/api/token. The token response includes `refresh_token`. When a later call returns `401` with `error="invalid_token"`, the client repeats the token request with `grant_type=refresh_token`. The account holder does not paste an access token.

## Identity methods

Accounts are email identities. Two sign-in methods are supported:

- **Local account.** The account holder registers with an email and password at https://panopticscans.com/register. When this deployment requires email verification, they open the verification message before signing in. They sign in at https://panopticscans.com/login.
- **Google.** The account holder signs in with Google at https://panopticscans.com/auth/google. Google is the identity provider and supplies the account email.

The machine-readable method is `verified_email`. The account holder claims that email by signing in. `register_uri` and `identity_endpoint` are the local registration page. `claim_uri` and `claim_endpoint` are the sign-in page, which also starts Google sign-in.

## Credentials

1. The account holder creates the account with local registration or Google, then signs in.
2. While signed in, they create an API key at https://panopticscans.com/settings/api. The key is a secret. Store it in a password manager or a client secret store, and give each integration its own key.
3. Exchange the API key for an access token. Send the key only to this endpoint:

```
POST https://panopticscans.com/api/token?key=API_KEY
```

The JSON response includes `access_token`, `token` (the same value), `refresh_token`, `token_type` (`bearer`), and `expires_in` (seconds). Keep the refresh token with the API key. It is a secret.

4. Call the API or the MCP server with the header `Authorization: Bearer ACCESS_TOKEN`.

The REST API base is https://panopticscans.com/api. The MCP endpoint is Streamable HTTP:

```
POST https://panopticscans.com/mcp
```

Send `Accept: application/json, text/event-stream` and `Authorization: Bearer ACCESS_TOKEN`. The initialize response sets `Mcp-Session-Id`; send that header on later requests. The same token covers scans, reports, vulnerabilities, targets, and webhooks.

When the access token expires, the API and the MCP server respond with `401` and `WWW-Authenticate: Bearer error="invalid_token"`. Exchange the refresh token. Send it only to this endpoint, as form or JSON:

```
POST https://panopticscans.com/api/token
grant_type=refresh_token&refresh_token=REFRESH_TOKEN
```

The response is a new access token and a new refresh token. Discard the refresh token you just sent. A refresh token that has already been used is rejected, and the tokens issued after it are revoked too. Do not send the API key or the refresh token on other API or MCP requests.

To revoke access, the account holder deletes the API key in Settings. Further key exchanges and refresh grants then fail. Access tokens that were already issued stop working when they expire.

An access token covers the signed-in account's API and MCP access. It is not narrowed to a subset of the scopes below. Subscription limits still apply.

After a trial ends, or after a subscription is cancelled, the account cannot exchange an API key, an authorization code, or a refresh token. `/api/login` and `/api/refresh` refuse those accounts as well. The response is `402` with `error` set to `payment_required` and `error_description` set to the upgrade message. An access token that was already issued keeps working until it expires. Creating a scan or rerunning one returns `402` immediately.

`/mcp` allows 60 authenticated requests per minute for an account. The tools `create_scan`, `rerun_scan`, and `test_webhook` allow 5 calls per minute each. Over the limit, the response is `429` with a `Retry-After` header.

- `scans.read` — List scans, scan runs, and report downloads.
- `scans.write` — Create, update, rerun, and delete scans.
- `vulnerabilities.read` — List and export vulnerabilities.
- `vulnerabilities.write` — Accept a vulnerability, mark it a false positive, or undo that decision.
- `targets.read` — List targets and the vulnerabilities on a target.
- `targets.write` — Delete a target.
- `webhooks.read` — List webhooks and their deliveries.
- `webhooks.write` — Create, update, delete, and test webhooks.


## Discovery

Protected Resource Metadata: [https://panopticscans.com/.well-known/oauth-protected-resource](https://panopticscans.com/.well-known/oauth-protected-resource)

Authorization Server metadata: [https://panopticscans.com/.well-known/oauth-authorization-server](https://panopticscans.com/.well-known/oauth-authorization-server)

The protected resource document lists `https://panopticscans.com` in `authorization_servers`. The authorization server document's `issuer` is that same URL. `bearer_methods_supported` is `header`. `agent_auth.skill` is this file.

MCP server card: [https://panopticscans.com/.well-known/mcp/server-card.json](https://panopticscans.com/.well-known/mcp/server-card.json)

A `401` from the API without a bearer token includes `WWW-Authenticate: Bearer resource_metadata="https://panopticscans.com/.well-known/oauth-protected-resource"`. A `401` from `/mcp` uses `resource_metadata="https://panopticscans.com/.well-known/oauth-protected-resource/mcp"`. A `401` for an expired or malformed access token also includes `error="invalid_token"`. A `401` for a token that still parses includes `error="insufficient_scope"` and should not be refreshed.

## Policies

- Pricing: https://panopticscans.com/pricing
- Terms of service: https://panopticscans.com/terms
- Privacy policy: https://panopticscans.com/privacy
- Integration help: support@panopticscans.com
