Authenticate to the Parquet API

Obtain a Control access token with OAuth 2.0 authorization code and PKCE.

The Parquet API uses Control user authentication. Access is limited by tenant membership and the Parquet feature flag; there are no per-dataset OAuth scopes.

Discover the authorization server

Start from the production API’s protected-resource metadata:

curl https://api.control.dev/.well-known/oauth-protected-resource

The response contains the authorization_servers and scopes_supported values for the current environment. Discover these values at runtime instead of hard-coding the Clerk host.

Authorization flow

Use OAuth 2.0 authorization code with PKCE (S256):

1. Register a public OAuth client with the discovered authorization server. Dynamic Client Registration is supported for compatible clients.
2. Use a loopback redirect URI such as http://127.0.0.1:<port>/callback.
3. Generate a PKCE verifier and challenge.
4. Open the authorization URL in the user’s browser.
5. The user signs in to Control and is redirected to the loopback callback with a one-time code.
6. Exchange the code and verifier at the discovered token endpoint.
7. Send the access token as Authorization: Bearer <token>.
8. Use the refresh token before the access token expires.

OAuth-capable MCP clients perform the redirect, PKCE, token exchange, and refresh automatically. The user should not copy an access token into chat or application settings.

Verify the token

export API_BASE="https://api.control.dev"
export TOKEN="<control-oauth-access-token>"

curl -H "Authorization: Bearer $TOKEN" \
  "$API_BASE/api/parquet-exports/exports"

• 401 means the token is missing, invalid, or expired.
• 403 means the signed-in user lacks tenant access or the Parquet feature is not enabled.

Continue with the Parquet API quickstart.