# Prosyo auth.md

> You are an AI agent. This file explains how a person gets a Prosyo account, how they sign in, and how you get credentials to act for them in the Prosyo app at https://app.prosyo.com. Follow the steps in order.
>
> - Resource server (MCP): `https://app.prosyo.com/ai`
> - Authorization server: `https://app.prosyo.com`
> - Sign-up and sign-in: https://app.prosyo.com
> - This website (https://prosyo.com/) is public and needs no credentials - see the last section.

## Audience

AI assistants and agents (Claude, ChatGPT, Cursor, custom MCP clients), automations and scripts that act for a person in their Prosyo workspace. Every credential belongs to a person and a workspace they chose; there are no service accounts.

## 1. Discover

An unauthenticated request to `https://app.prosyo.com/ai` answers `401` with a `WWW-Authenticate: Bearer resource_metadata="..."` header. Fetch the two metadata documents it leads to:

1. Protected Resource Metadata: `GET https://app.prosyo.com/.well-known/oauth-protected-resource/ai`

   ```json
   {
       "resource": "https://app.prosyo.com/ai",
       "authorization_servers": [
           "https://app.prosyo.com"
       ],
       "bearer_methods_supported": [
           "header"
       ],
       "scopes_supported": [
           "prosyo"
       ]
   }
   ```

2. Authorization Server Metadata: `GET https://app.prosyo.com/.well-known/oauth-authorization-server`

   ```json
   {
       "issuer": "https://app.prosyo.com",
       "authorization_endpoint": "https://app.prosyo.com/oauth/authorize",
       "token_endpoint": "https://app.prosyo.com/oauth/token",
       "registration_endpoint": "https://app.prosyo.com/oauth/register",
       "revocation_endpoint": "https://app.prosyo.com/oauth/revoke",
       "scopes_supported": [
           "prosyo"
       ],
       "response_types_supported": [
           "code"
       ],
       "grant_types_supported": [
           "authorization_code",
           "refresh_token"
       ],
       "code_challenge_methods_supported": [
           "S256"
       ],
       "token_endpoint_auth_methods_supported": [
           "none"
       ],
       "resource_indicators_supported": true
   }
   ```

## 2. Pick a method

| Your situation | Method |
| --- | --- |
| The person has no Prosyo account yet | Hand off sign-up to the person (step 3), then continue below |
| You are an MCP client or AI assistant | OAuth 2.1 authorization code with PKCE (step 4) |
| You are a script, automation or backend job | API token created by the person (step 6) |

**Not supported:** There is no agent self-registration (`identity_assertion`, `service_auth` or `anonymous` agent registration) and no password login. A person must sign up and approve access in a browser.

## 3. Register: the person creates the account

1. Send the person to **https://app.prosyo.com**. The same page is used to sign up and to sign in.
2. They sign up with: Continue with Google, or a magic link sent to a work email. There is no password.
3. A short onboarding asks for their company, goal and ideal customer profile, then creates their workspace.
4. Every new workspace starts with a 7-day free trial. No credit card required.

Do not create accounts on your own, enter a person's email on a sign-up form without their consent, or read their inbox to open a sign-in link. The person completes sign-up themselves.

Guide: https://prosyo.com/docs/getting-started/create-account/

## 4. Sign in and authorize (MCP clients)

Most MCP clients do all of this for you: add a remote MCP server with the URL `https://app.prosyo.com/ai` and OAuth authentication, then click Connect. The steps underneath:

1. Register a client (RFC 7591): `POST https://app.prosyo.com/oauth/register`

   ```json
   {
       "client_name": "Your Agent",
       "redirect_uris": [
           "https://your-agent.example/oauth/callback"
       ],
       "grant_types": [
           "authorization_code",
           "refresh_token"
       ],
       "response_types": [
           "code"
       ],
       "token_endpoint_auth_method": "none"
   }
   ```

2. Create a PKCE code verifier, then open this URL in the person's browser:

   ```
   https://app.prosyo.com/oauth/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&scope=prosyo&state={state}&code_challenge={code_challenge}&code_challenge_method=S256&resource=https%3A%2F%2Fapp.prosyo.com%2Fai
   ```

3. The person signs in, chooses the workspace and clicks **Allow**. Their browser returns to your redirect URI with `code` and `state`.
4. Exchange the code (form-encoded): `POST https://app.prosyo.com/oauth/token` with `grant_type=authorization_code`, `code`, `redirect_uri`, `client_id`, `code_verifier`, `resource=https://app.prosyo.com/ai`.
5. When the access token expires, refresh it at the same endpoint with `grant_type=refresh_token`, `refresh_token`, `client_id`, `resource=https://app.prosyo.com/ai`.

Guide: https://prosyo.com/docs/ai/connect-claude/

## 5. Use the access token

- Send `Authorization: Bearer <access_token>` with every request to `https://app.prosyo.com/ai` (MCP, Streamable HTTP). Tokens go in the header only, never in a URL.
- Scope `prosyo` covers the one workspace the person chose on the Allow screen.
- Reading campaigns, lists, prospects and the inbox runs straight away. Launching or resuming campaigns, enrolling prospects and sending replies need the person's explicit yes in the conversation.
- Agents cannot connect LinkedIn or email accounts, change billing or buy credits; the person does that in Prosyo.

## 6. API tokens (scripts and automations)

- The person creates a token in Prosyo under **Integrations → Chrome extension & API → Generate API token** and gives it to you.
- Base URL: `https://app.prosyo.com/api/v1/ext` · header `Authorization: Bearer <token>`
- A token acts as the person who created it, with their role, workspace and plan limits.

```
curl https://app.prosyo.com/api/v1/ext/session -H "Authorization: Bearer $TOKEN"
```

Reference: https://prosyo.com/docs/integrations/api-reference/

## 7. Errors

| Status | Meaning | What to do |
| --- | --- | --- |
| 401 | Missing, expired or revoked credential | Refresh the token, or ask the person to authorize again |
| 403 | The person's role or plan does not allow it | Tell the person; do not retry |
| 404 | Not found in this workspace | Check you are using the workspace the person chose |
| 429 | Rate limited | Wait a minute, then retry |

## 8. Revocation

- OAuth tokens: `POST https://app.prosyo.com/oauth/revoke` (RFC 7009) with `token` and `client_id`.
- The person can disconnect any assistant at any time in Prosyo under **Integrations**; access stops immediately.
- API tokens are replaced with **Rotate token** or cut off with **Revoke all tokens**.

## Credential rules

- Never ask a person for a password; there is none.
- Send tokens only to app.prosyo.com, over HTTPS, in the Authorization header.
- Keep tokens secret and never pass a person's token to another service or agent.

## This website: Prosyo (https://prosyo.com/)

The marketing site, blog and docs need no credentials and no registration (`identity_types_supported: ["anonymous"]`). Its agent endpoints are public and read-only; do not send app tokens to them.

| Endpoint | URL | Purpose | Auth |
| --- | --- | --- | --- |
| Any page with `Accept: text/markdown` | https://prosyo.com/ | Page content as Markdown | none |
| Agent API | https://prosyo.com/ai/ | Search, read and list content (OpenAPI: /ai/openapi.json) | none |
| MCP | https://prosyo.com/ai/mcp | Read-only MCP tools | none |
| A2A | https://prosyo.com/ai/a2a | Agent-to-agent questions | none |

### Identifying your agent

- Send a descriptive `User-Agent` with a contact URL.
- Web Bot Auth signatures (`Signature-Agent`, `Signature-Input`, `Signature`) are welcome but not required.
- Requests this site sends are signed; verify them with the keys at https://prosyo.com/.well-known/http-message-signatures-directory.

### Usage

- Keep to a few requests per second and honour `Cache-Control`.
- Content-use preferences are declared with Content-Signal in https://prosyo.com/robots.txt.

## Contact

https://prosyo.com/contact-us