---
title: "Authentication and access"
description: "API keys, OAuth 2.1 with PKCE and device flow, credential scopes, and why tokens never cross between Studio and Runtime planes."
canonical: "https://grid82.com/docs/start/authentication-and-access"
updated: "2026-11-20"
---

# Authentication and access

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 key**                                               | **Studio builder key**                                         |
| -------------- | ----------------------------------------------------------------- | -------------------------------------------------------------- |
| Created in     | App menu -> **Settings** -> **Connections** -> **For developers** | Studio -> **Developer**                                        |
| Acts as        | You, inside that single app                                       | You, inside one selected organisation                          |
| Default expiry | 90 days                                                           | 90 days by default, custom days, or never                      |
| Visibility     | Shown once at creation; revoked immediately in the same screen    | Shown 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:

```bash title="Runtime app key"
curl "https://your-suite.grid82.app/your-app/v1/me" \
  -H "Authorization: Bearer $GRID82_TOKEN"
```

```bash title="Studio builder key"
curl "https://studio.grid82.app/v1/session" \
  -H "Authorization: Bearer $GRID82_TOKEN"
```

## Scopes

| Scope           | Allows                                                                                                        | Available in Runtime apps |
| --------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `records:read`  | List, get, count, and summarise records, read comments, history, views, and run SQL `SELECT`                  | Yes                       |
| `records:write` | Create, update, duplicate, and delete records, post comments, upload files, run SQL writes, revert changesets | Yes                       |
| `schema:read`   | Inspect accessible tables, fields, and permission rules                                                       | Yes                       |
| `schema:write`  | Modify tables, fields, and permission rules                                                                   | Studio only               |
| `pages:read`    | Read Interface pages, source code, and versions                                                               | Yes                       |
| `pages:write`   | Create, update, and publish Interface pages (personal pages in Runtime; app pages in Studio)                  | Yes                       |
| `members:read`  | List app members and suite users                                                                              | Yes                       |
| `members:write` | Invite users, assign roles, and manage invite links                                                           | Studio only               |
| `account:read`  | Read organisations, suites, apps, plans, and usage                                                            | Studio only               |
| `account:write` | Create or leave organisations, update org settings, delete accounts                                           | Studio 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.

| Endpoint             | Path 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.
