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

# Authentication

The CorralData MCP Server uses OAuth 2.0 for authentication. You sign in once through your organization's identity provider, and the server handles token management automatically.

## How authentication works

When you connect to CorralData from Claude, ChatGPT, Claude Code, Codex, or any other MCP client, the following happens:

1. **Your assistant redirects you** to your organization's login page
2. **You sign in** with your existing CorralData credentials
3. **You grant permissions** for the assistant to access CorralData tools on your behalf
4. **The assistant receives a token** and uses it for all subsequent tool calls
5. **Tokens refresh automatically** — you won't need to sign in again unless your session expires

### Client ID and client secret

Every MCP client identifies itself to CorralData with the public OAuth client ID `corral-mcp-client`. There is **no client secret**: the client is a public OAuth client protected by PKCE (Proof Key for Code Exchange), which is the standard for desktop tools and command-line clients that cannot keep a secret. If a setup form requires a client secret, enter any value; it is not checked.

The client ID only tells CorralData which application is asking. Your own login is what decides what data you can see.

## Roles and permissions

What you can do through your assistant depends on the roles assigned to your account in CorralData.

Permissions come from your CorralData role. These are the default roles. CorralData can set up custom roles for your account.

| Permission         | What it unlocks                                                                                                                                          | Default roles that include it                                                                                                                                                  |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| *None*             | Browse boards, widgets, filters, data models and Data Apps; list schemas and tables; lint SQL; connected services; prompts; your own custom instructions | Every role                                                                                                                                                                     |
| **sql.execute**    | Run SQL and read column-level detail: `execute_sql`, `describe_table`, `describe_tables`, `get_column_values`                                            | Editor, Admin                                                                                                                                                                  |
| **board.edit**     | Create, duplicate, change and reorder boards; manage board filters                                                                                       | Editor, Admin                                                                                                                                                                  |
| **widget.edit**    | Create and change widgets, data models and Data Apps                                                                                                     | Editor, Admin                                                                                                                                                                  |
| **company.edit**   | Set the account's AskCorral custom instructions                                                                                                          | Admin                                                                                                                                                                          |
| **security.admin** | All row-level security tools                                                                                                                             | Not in any default role. To manage row-level security (identities, secured tables, access mappings, and table and value grants), ask the CorralData team to set it up for you. |

Viewer and Reports Only roles can't run SQL through the MCP server. To run SQL, a user needs the Editor or Admin role, or a custom role from CorralData that includes `sql.execute`.

Permissions apply per company. CorralData checks your role in the company you work in on every request, so a role in one company does not let you change another company's data.

The [Tools Reference](https://docs.corraldata.com/kb/mcp/tools-reference.md) lists the permission each tool needs.

If you try an action you don't have permission for, your assistant will let you know. Contact your CorralData administrator to request additional roles.

## Security

* Authentication uses the OAuth 2.0 Authorization Code flow with PKCE (S256), enforced for every login
* The OAuth client is public by design: there is no shared secret to leak, and a client ID alone grants no access
* All communication is encrypted over HTTPS
* Tokens are validated server-side. Access tokens expire after 30 minutes. Your AI client renews them, so you stay signed in until you remove the integration or stop using it for 30 days.
* To disconnect, remove the CorralData connector in your AI client. Signing out of the CorralData web app does not disconnect your AI client.

For how your data is handled, see [HIPAA, PHI and AI](https://docs.corraldata.com/kb/security-and-privacy/hipaa-phi-ai.md).


---

# 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.corraldata.com/kb/mcp/authentication.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.
