Grid82
grid82.comJoin the waitlist
Get startedAuthentication

Authentication and access

API keys, OAuth 2.1 with PKCE and device flow, credential scopes, and why tokens never cross between Studio and Runtime planes.

Every credential in Grid82 acts as one person, on one plane, bounded by the scopes granted to that credential. There is no ambient admin token and no global service account.

Bearer tokens and plane isolation

Both API keys and OAuth access tokens are sent as standard bearer tokens:

HTTP
Authorization: Bearer g82_live_...

Keys start with g82_. Every credential is issued for either the Studio (studio.grid82.app) or a Suite / App ({suite}.grid82.app). Presenting a Runtime token to the Studio API (or a Studio token to an app’s Runtime API) always returns 401 unauthenticated.

A credential can only narrow a person’s permissions. Giving records:write scope to a user whose roles only grant read access still blocks writes with 403 forbidden.

API keys

Runtime app keyStudio builder key
Created inApp menu -> Settings -> Connections -> For developersStudio -> Developer
Acts asYou, inside that single appYou, inside one selected organisation
Default expiry90 days90 days by default, custom days, or never
VisibilityShown once at creation; revoked immediately in the same screenShown once at creation; revoked immediately in the same screen

API keys and OAuth tokens cannot mint or revoke API keys. Only a person in a signed-in browser session can create or revoke keys, ensuring a leaked key cannot create persistence for itself.

Verify any credential against its identity endpoint:

Runtime app key
curl "https://your-suite.grid82.app/your-app/v1/me" \
  -H "Authorization: Bearer $GRID82_TOKEN"
Studio builder key
curl "https://studio.grid82.app/v1/session" \
  -H "Authorization: Bearer $GRID82_TOKEN"

Scopes

ScopeAllowsAvailable in Runtime apps
records:readList, get, count, and summarise records, read comments, history, views, and run SQL SELECTYes
records:writeCreate, update, duplicate, and delete records, post comments, upload files, run SQL writes, revert changesetsYes
schema:readInspect accessible tables, fields, and permission rulesYes
schema:writeModify tables, fields, and permission rulesStudio only
pages:readRead Interface pages, source code, and versionsYes
pages:writeCreate, update, and publish Interface pages (personal pages in Runtime; app pages in Studio)Yes
members:readList app members and suite usersYes
members:writeInvite users, assign roles, and manage invite linksStudio only
account:readRead organisations, suites, apps, plans, and usageStudio only
account:writeCreate or leave organisations, update org settings, delete accountsStudio only

OAuth 2.1 for CLI and MCP clients

The Studio and every suite run their own OAuth 2.1 authorization servers so agents and CLI sessions never ask you to copy-paste secrets into prompts or config files.

  • Discovery. RFC 8414 (/.well-known/oauth-authorization-server) and RFC 9728 (/.well-known/oauth-protected-resource) are served on https://studio.grid82.app and on every suite host. Unauthenticated /mcp calls return 401 with a WWW-Authenticate challenge pointing to the authorization metadata.
  • PKCE (S256 only). All native and web clients are public clients using Authorization Code + PKCE. plain challenges and implicit flows are disabled.
  • Device authorization flow. Supported via urn:ietf:params:oauth:grant-type:device_code for SSH sessions, containers, and CI setups (grid82 auth login --device). Users enter the displayed code on the verification page and confirm it on the consent screen.
  • Dynamic client registration. Clients without a metadata document can register dynamically at /oauth/register (RFC 7591).
  • Token lifetimes and rotation. Access tokens live for 30 days, and refresh tokens live for 90 days. Every refresh rotates the refresh token; reusing an old refresh token invalidates the entire grant immediately.
EndpointPath on Studio or suite origin
Authorize/authorize
Token/oauth/token
Device authorization/oauth/device
Registration/oauth/register
Revocation/oauth/revoke

On the browser consent screen, verify the client’s name and redirect URI, check which scopes are requested, and select which apps of the suite (or which Studio organisation) the connection may access.

Auth rate limits

Sign-in and OAuth endpoints rate-limit requests per IP address per minute and return 429 rate_limited when exceeded. Wait one minute before retrying.

Use these docs with your AI tools

An AI agent can read this documentation directly. You do not need an account or an API key. Everything here is public and read-only.

Query these docs via MCP

Recommended

Add this server to Claude, Claude Code, Cursor, Mistral, or any tool that supports MCP. Your agent can then search Grid82 documentation and read it in full, instead of answering from memory.

https://grid82.com/docs/mcp
  • searchFind the passages that answer a question.
  • fetchRead one page in full, as Markdown.
  • list_pagesSee every page in this documentation.

Query these docs over HTTP

The same tools also work as plain web requests. Use this for scripts, or for any tool that does not support MCP. There is one endpoint per tool. Arguments go in the query string, and the answer comes back as JSON.

https://grid82.com/docs/api/docs/search?query=custom+domain

Read the OpenAPI description. It is built from the same definitions as the tools, so it always matches what the endpoints do.

Read these docs as Markdown

Add .md to any page URL to get its Markdown source. You can also send the headerAccept: text/markdown to the page URL itself.

To read the whole documentation in one file, open llms-full.txt. For a short index of every page, open llms.txt.