> ## Documentation Index
> Fetch the complete documentation index at: https://docs.copyfy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Sign in with OAuth or use a personal API key, and manage connected apps and keys from the Copyfy dashboard.

The Copyfy MCP accepts two kinds of credentials. Both give read-only access to Copyfy Discovery data and share the same [quota](/quotas-and-limits).

| Method                  | Best for                                                                                    | How it works                                                                                       |
| ----------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| **OAuth** (recommended) | Claude, ChatGPT, Perplexity, Cursor, Claude Code, Codex, VS Code, Gemini CLI, Devin Desktop | Your client opens a Copyfy sign-in page. You approve access once and the client stores the tokens. |
| **API key**             | Clients that send a custom header, scripts, CI, shared machines without a browser           | You create a key on the dashboard and add it to the client as an `Authorization: Bearer` header.   |

## OAuth

OAuth is the default for every client that supports it. You never copy a secret.

<Steps>
  <Step title="Add the server URL to your client">
    Paste `https://app.copyfy.io/mcp` in your client. It discovers the Copyfy authorization server automatically.
  </Step>

  <Step title="Sign in to Copyfy">
    Your browser opens the Copyfy sign-in page. If you are already signed in to Copyfy, this step is skipped.
  </Step>

  <Step title="Review the consent screen">
    The consent screen, titled **Connect (app name) to Copyfy**, shows:

    * **Returns you to**: the website or app that receives access, for example `claude.ai` or `chatgpt.com`.
    * **Published by**: the verified publisher of the app, when the app publishes its identity. Otherwise the screen says the app chose its own name.
    * **Signed in as**: your Copyfy account. Use **Use another account** to switch.
    * What the app can do: search Copyfy shops, products, and ads, without changing your account, stores, or billing.

    Apps that run on your computer often return to a local address (`localhost` or `127.0.0.1`). Copyfy then warns you to continue only if you just started the connection yourself.
  </Step>

  <Step title="Click Allow access">
    You return to your client, which is now connected. Growth and Pro accounts see **Allow access**; other plans see an upgrade or billing prompt instead.
  </Step>
</Steps>

<Warning>
  If **Returns you to** shows a website you do not recognize, or you did not start the connection, click **Cancel**. An app can choose any name, but **Returns you to** is where Copyfy sends your approval, so it tells you who actually receives access.
</Warning>

### Scope and token lifetime

* The only scope is `discovery:read`: read Copyfy Discovery data (stores, products, ads). No client can change your account, your tracked stores, or your billing.
* Access tokens last 1 hour. Refresh tokens last 30 days and rotate on every use, so an active client stays connected without asking you to sign in again.
* If a client stays unused for more than 30 days, it asks you to sign in again.

### Disconnect an app

Every approved client appears under **Connected apps** on the [Integrations page](https://app.copyfy.io/dashboard/api), with the date it connected and when it was last used. Click **Revoke** to disconnect it. Its tokens stop working immediately; the client asks you to sign in again the next time it calls Copyfy.

## API keys

Use an API key when your client supports custom headers and you prefer not to use OAuth, or when no browser is available.

### Create a key

<Steps>
  <Step title="Open the Integrations page">
    Go to [app.copyfy.io/dashboard/api](https://app.copyfy.io/dashboard/api). You need an active Growth or Pro subscription to create keys.
  </Step>

  <Step title="Create the key">
    Under **API keys**, click **Create key** and give it a name that says where you will use it, for example `Cursor laptop` (up to 60 characters).
  </Step>

  <Step title="Copy the key now">
    Copyfy shows the key once. Copy it and store it in your client or in a password manager. You cannot display it again later; if you lose it, create a new one.
  </Step>
</Steps>

Keys start with `cpy_` and are followed by 43 characters. The dashboard only shows the last four characters (`cpy_…a1b2`). You can have up to 10 active keys and create up to 20 keys per hour.

### Use a key

Send the key in the `Authorization` header of every request:

```http theme={null}
Authorization: Bearer cpy_your_key_here
```

Each [connection guide](/quickstart) shows where to put the header for that client. To check a key from a terminal, call the free `get_usage` tool:

```bash Terminal theme={null}
curl https://app.copyfy.io/mcp \
  -H "Authorization: Bearer $COPYFY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_usage","arguments":{}}}'
```

A valid key returns your plan and remaining credits. An unknown or revoked key returns HTTP `401 Unauthorized`.

### Rotate a key

1. Create a new key.
2. Replace the old key in your client and restart or reload the client.
3. Revoke the old key.

### Revoke a key

On the Integrations page, click **Revoke** next to the key. It stops working immediately, and clients that still use it get HTTP `401 Unauthorized`.

### Keep keys safe

* Treat a key like a password. Anyone with the key can spend your MCP credits.
* Never paste a key into a chat, a shared document, or a support ticket, and never commit it to a repository. Reference it from an environment variable when your client supports it.
* Use one key per client or machine, so you can revoke one without breaking the others.
* If a key leaks, revoke it right away and create a new one.

<Note>
  If your subscription is downgraded, paused, or unpaid, your keys and connected apps are kept but tool calls return an error such as `plan_upgrade_required`. They work again as soon as the subscription is active on Growth or Pro. See [Errors](/errors).
</Note>

## For client developers

Copyfy follows the [MCP authorization specification](https://modelcontextprotocol.io/specification/latest/basic/authorization):

* Protected resource metadata (RFC 9728): `https://app.copyfy.io/.well-known/oauth-protected-resource/mcp`
* Authorization server metadata (RFC 8414): `https://app.copyfy.io/.well-known/oauth-authorization-server`
* Authorization code flow with PKCE (`S256` only) and the `resource` parameter set to `https://app.copyfy.io/mcp` (RFC 8707).
* Client registration through Client ID Metadata Documents or Dynamic Client Registration (RFC 7591).
* Tokens are sent in the `Authorization` header only. Unauthenticated requests get HTTP `401` with a `WWW-Authenticate` header that points to the protected resource metadata.