> For the complete documentation index, see [llms.txt](https://docs.zigpoll.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zigpoll.com/integrations/oauth-apps.md).

# OAuth Apps

Let other Zigpoll accounts connect to your app with OAuth, read-only, without sharing an API key

Use an OAuth app when you build a product that reads Zigpoll data for **other** brands: an agency tool, an analytics product or a testing platform. Each brand clicks your "Connect Zigpoll" button, signs in to Zigpoll, chooses which of their accounts to share and approves. You get a token for exactly those accounts. Nobody copies an API key.

If you only need your own data, use an [API key](https://docs.zigpoll.com/integrations/api-key.md) instead.

### What an app can do

OAuth apps get one scope, `read`:

* Read surveys, questions and responses in the accounts the brand chose.
* Nothing else. Apps cannot create, change or delete anything, and cannot send emails or SMS.

Brands can remove your app at any time under **Integrations → Connected Apps**. Access ends immediately. It also ends if the person who connected it leaves the account or stops being an admin.

### 🔑 Create an app

* Go to **Integrations → OAuth Apps** and click **New App**.
* Enter your app's name, website and one or more **redirect URIs** (your OAuth callback URLs).
* Copy the **client ID** and **client secret**. The secret is shown only once. You can generate a new one at any time.

Creating an app requires an Owner, Admin or Billing Admin role, on any plan. Brands connecting your app can only choose accounts they administer that are on a plan with API access (Premium or higher).

New apps are **unverified**, and brands see a warning when they connect. [Contact us](https://www.zigpoll.com/contact) to have your app reviewed.

Redirect URIs must use `https://` (`http://` is allowed for `localhost` while you develop). They are matched exactly, including the path and query string.

### 🔁 The flow

Zigpoll uses the OAuth 2.1 authorization code flow with PKCE.

|                       |                                                   |
| --------------------- | ------------------------------------------------- |
| Authorization URL     | `https://mcp.zigpoll.com/authorize`               |
| Token URL             | `https://mcp.zigpoll.com/token`                   |
| Revocation URL        | `https://mcp.zigpoll.com/revoke`                  |
| Scope                 | `read`                                            |
| PKCE                  | Required, `S256`                                  |
| Client authentication | `client_secret_post` (secret in the request body) |
| API base URL          | `https://v1.zigpoll.com`                          |

**1. Send the brand to Zigpoll**

```
https://mcp.zigpoll.com/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/oauth/zigpoll/callback
  &scope=read
  &state=RANDOM_STATE
  &code_challenge=BASE64URL(SHA256(code_verifier))
  &code_challenge_method=S256
```

The brand signs in, picks accounts and approves. Zigpoll then redirects to your `redirect_uri` with `code` and `state`. If they deny, you get `error=access_denied` instead.

**2. Exchange the code**

Send the same `redirect_uri` you used in step 1; it is required.

```bash
curl -X POST https://mcp.zigpoll.com/token \
  -d grant_type=authorization_code \
  -d code=CODE \
  -d code_verifier=CODE_VERIFIER \
  -d redirect_uri=https://yourapp.com/oauth/zigpoll/callback \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET
```

```json
{
  "access_token": "zpat_…",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "read",
  "refresh_token": "zprt_…"
}
```

**3. Call the API**

```bash
curl https://v1.zigpoll.com/accounts -H "Authorization: Bearer zpat_…"
```

**4. Refresh**

Access tokens last one hour. Exchange the refresh token for a new pair:

```bash
curl -X POST https://mcp.zigpoll.com/token \
  -d grant_type=refresh_token \
  -d refresh_token=zprt_… \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET
```

Every refresh returns a **new refresh token** and invalidates the old one, so always store the latest. If two refreshes race with the same token, only one succeeds. Presenting an old refresh token more than a minute after it was replaced is treated as theft and **ends the connection**. Connections unused for 90 days expire. An `invalid_grant` error means the brand removed your app, the connection expired, or the token was already used. Ask the brand to connect again.

### 📚 Endpoints you can call

All are `GET` requests to `https://v1.zigpoll.com`, documented in the [API reference](https://apidocs.zigpoll.com/).

| Endpoint              | Returns                                                                                                                  |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `/me`                 | The connecting user's id and the accounts they shared                                                                    |
| `/accounts`           | The shared accounts                                                                                                      |
| `/account?accountId=` | One account                                                                                                              |
| `/surveys?accountId=` | Surveys (omit `accountId` for every shared account)                                                                      |
| `/survey?pollId=`     | One survey                                                                                                               |
| `/questions?pollId=`  | A survey's questions                                                                                                     |
| `/question?slideId=`  | One question                                                                                                             |
| `/responses?pollId=`  | Responses, newest first. Also takes `accountId` or `slideId`, `createdAfter`, `createdBefore`, `limit` and `startCursor` |

Responses are paginated. Pass the response's `endCursor` as `startCursor` until `hasNextPage` is `false`.

Apps see survey content and results, not configuration: account plan and team details, survey and question settings, action logic and reward codes are left out of these responses.

Any other endpoint, and any write, returns `403`. An id outside the shared accounts returns `404`. An expired or revoked access token returns `401` with `WWW-Authenticate: Bearer error="invalid_token"`: refresh and retry once.

### 🔒 Good practice

* Keep the client secret on your server. Never ship it in a browser or mobile app.
* Check that `state` matches what you sent before exchanging a code.
* Store tokens encrypted. Zigpoll stores only hashes of them.
* To disconnect a brand from your side, call the revocation URL with either token (plus your client ID and secret). The whole grant ends.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.zigpoll.com/integrations/oauth-apps.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
